Skip to main content

​
Widget Actions

Actions allow widget components to trigger dynamic behaviors like sending messages, showing notifications, or making network requests.

​
Action Format

Actions are objects with a type and optional payload: 
interface WidgetAction {
  type: string;          // Action type (e.g., 'lyzn.sendMessage')
  payload?: object;      // Action-specific parameters
}

​
Standard Action Types

​
lyzn.sendMessage

Send collected form data as a chat message. 
<Button
  label="Submit"
  onClickAction={{
    type: "lyzn.sendMessage",
    payload: { message: "Form submitted" }
  }}
/>
Payload:
PropertyTypeDescription
messagestringOptional custom message. If omitted, sends form data as JSON
includeFormDatabooleanWhether to include form data (default: true)

​
lyzn.showToast

Display a toast notification to the user. 
<Button
  label="Save"
  onClickAction={{
    type: "lyzn.showToast",
    payload: { message: "Changes saved!", type: "success" }
  }}
/>
Payload:
PropertyTypeDescription
messagestringRequired. Toast message text
type’success’ | ‘error’ | ‘info’Toast type (default: ‘info’)
Open a URL in webview or external browser. 
<Button
  label="Open Settings"
  onClickAction={{
    type: "lyzn.openLink",
    payload: { url: "myapp://settings" }
  }}
/>

<Button
  label="Visit Website"
  onClickAction={{
    type: "lyzn.openLink",
    payload: { url: "https://example.com", external: true }
  }}
/>
Payload:
PropertyTypeDescription
urlstringRequired. URL or deeplink to open
externalbooleanOpen in external browser (default: false)

​
lyzn.resetState

Reset the widget’s form state. 
<Button
  label="Clear Form"
  onClickAction={{ type: "lyzn.resetState" }}
/>

<Button
  label="Clear Name"
  onClickAction={{
    type: "lyzn.resetState",
    payload: { fields: ["firstName", "lastName"] }
  }}
/>
Payload:
PropertyTypeDescription
fieldsstring[]Optional. Specific fields to reset. Resets all if omitted

​
lyzn.fetch

Make a network request. 
<Select
  name="country"
  options={countries}
  action={{
    type: "lyzn.fetch",
    payload: {
      url: "/api/cities",
      method: "GET"
    }
  }}
/>
Payload:
PropertyTypeDescription
urlstringRequired. Request URL
methodstringHTTP method (default: ‘GET’)
bodyobjectRequest body for POST/PUT
headersobjectAdditional headers

​
Using Actions

​
On Buttons

Use onClickAction or action prop: 
<Button
  label="Submit"
  onClickAction={{ type: "lyzn.sendMessage" }}
/>

​
On Form Components

Form components like Select, RadioGroup, and Checkbox support the action prop to trigger actions on value change: 
<Select
  name="theme"
  options={themes}
  action={{
    type: "lyzn.showToast",
    payload: { message: "Theme updated!" }
  }}
/>

​
On Cards

Use confirm and cancel props to add action buttons: 
<Card
  confirm={{
    label: "Submit",
    action: { type: "lyzn.sendMessage" }
  }}
  cancel={{
    label: "Reset",
    action: { type: "lyzn.resetState" }
  }}
>
  <Select name="option" options={options} />
</Card>

​
Form State Management

When a form component has a name prop, it updates the widget’s form state instead of sending a message immediately: 
// These selections update form state
<Select name="color" options={colors} />
<Select name="size" options={sizes} />

// This button sends all form data
<Button
  label="Confirm"
  onClickAction={{ type: "lyzn.sendMessage" }}
/>
The form data is collected as: 
{ "color": "red", "size": "large" }

​
Value Placeholders

Use {{value}} in action payloads to inject the current value: 
<Select
  name="country"
  options={countries}
  action={{
    type: "lyzn.showToast",
    payload: { message: "Selected: {{value}}" }
  }}
/>

​
Complete Example

<Card
  confirm={{
    label: "Generate Post",
    action: { type: "lyzn.sendMessage" }
  }}
>
  <Col gap={3}>
    <Title value="LinkedIn Post Setup" size="sm" />
    <Text value="Configure your post settings" size="sm" color="secondary" />
    <Divider />
    
    <Col gap={2}>
      <Label value="Tone" />
      <Select
        name="post.tone"
        options={[
          { value: "professional", label: "Professional" },
          { value: "casual", label: "Casual" },
          { value: "inspirational", label: "Inspirational" }
        ]}
        defaultValue="professional"
      />
    </Col>
    
    <Col gap={2}>
      <Label value="Length" />
      <RadioGroup
        name="post.length"
        options={[
          { value: "short", label: "Short" },
          { value: "medium", label: "Medium" },
          { value: "long", label: "Long" }
        ]}
        defaultValue="medium"
      />
    </Col>
    
    <Checkbox
      name="post.includeEmoji"
      label="Include emojis"
      defaultValue={true}
    />
  </Col>
</Card>
When user clicks “Generate Post”, this sends: 
{
  "post.tone": "professional",
  "post.length": "medium",
  "post.includeEmoji": true
}