> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> Execute dynamic behaviors from widget components

# 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`:

```typescript theme={null}
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.

```jsx theme={null}
<Button
  label="Submit"
  onClickAction={{
    type: "lyzn.sendMessage",
    payload: { message: "Form submitted" }
  }}
/>
```

**Payload:**

| Property          | Type    | Description                                                  |
| ----------------- | ------- | ------------------------------------------------------------ |
| `message`         | string  | Optional custom message. If omitted, sends form data as JSON |
| `includeFormData` | boolean | Whether to include form data (default: true)                 |

***

### lyzn.showToast

Display a toast notification to the user.

```jsx theme={null}
<Button
  label="Save"
  onClickAction={{
    type: "lyzn.showToast",
    payload: { message: "Changes saved!", type: "success" }
  }}
/>
```

**Payload:**

| Property  | Type                           | Description                  |
| --------- | ------------------------------ | ---------------------------- |
| `message` | string                         | Required. Toast message text |
| `type`    | 'success' \| 'error' \| 'info' | Toast type (default: 'info') |

***

### lyzn.openLink

Open a URL in webview or external browser.

```jsx theme={null}
<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:**

| Property   | Type    | Description                               |
| ---------- | ------- | ----------------------------------------- |
| `url`      | string  | Required. URL or deeplink to open         |
| `external` | boolean | Open in external browser (default: false) |

***

### lyzn.resetState

Reset the widget's form state.

```jsx theme={null}
<Button
  label="Clear Form"
  onClickAction={{ type: "lyzn.resetState" }}
/>

<Button
  label="Clear Name"
  onClickAction={{
    type: "lyzn.resetState",
    payload: { fields: ["firstName", "lastName"] }
  }}
/>
```

**Payload:**

| Property | Type      | Description                                               |
| -------- | --------- | --------------------------------------------------------- |
| `fields` | string\[] | Optional. Specific fields to reset. Resets all if omitted |

***

### lyzn.fetch

Make a network request.

```jsx theme={null}
<Select
  name="country"
  options={countries}
  action={{
    type: "lyzn.fetch",
    payload: {
      url: "/api/cities",
      method: "GET"
    }
  }}
/>
```

**Payload:**

| Property  | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `url`     | string | Required. Request URL        |
| `method`  | string | HTTP method (default: 'GET') |
| `body`    | object | Request body for POST/PUT    |
| `headers` | object | Additional headers           |

***

## Using Actions

### On Buttons

Use `onClickAction` or `action` prop:

```jsx theme={null}
<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:

```jsx theme={null}
<Select
  name="theme"
  options={themes}
  action={{
    type: "lyzn.showToast",
    payload: { message: "Theme updated!" }
  }}
/>
```

### On Cards

Use `confirm` and `cancel` props to add action buttons:

```jsx theme={null}
<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:

```jsx theme={null}
// 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:

```json theme={null}
{ "color": "red", "size": "large" }
```

***

## Value Placeholders

Use `{{value}}` in action payloads to inject the current value:

```jsx theme={null}
<Select
  name="country"
  options={countries}
  action={{
    type: "lyzn.showToast",
    payload: { message: "Selected: {{value}}" }
  }}
/>
```

***

## Complete Example

```jsx theme={null}
<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:

```json theme={null}
{
  "post.tone": "professional",
  "post.length": "medium",
  "post.includeEmoji": true
}
```