---
title: "Component reference"
description: "Widgets use layout, text, media, and interactive components. Use this reference to choose components and their supported props."
---

:::note[Plan]
Actions are available on the **Starter** plan and above.
:::

Every widget starts with `Card`. Leaf components (`Text`, `Title`, `Caption`, `Label`, `Image`, `Icon`, `Badge`, `Button`, `Spacer`, and `Divider`) cannot have children. Put text in `value` or `label`, rather than between tags.

Components and props outside this reference are refused on save. A prop not defined here produces an error, such as `<Button> has no prop "href".` A leaf with children produces, for example, `<Text> cannot have children.` A different root produces `Widget code must start with <Card>.`

The tables describe renderer values and defaults. A dash means no explicit prop default. An accepted prop name does not mean every value has a visual effect. Use the shared values below. Each fragment can go inside a root `Card`; the Card example is a complete widget. Button examples require the named function in **Functions**.

## Layout

### Card

Root card with an optional status and footer.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `size` | sm, md, lg, full | full | Maximum card width: 320, 384, 512px, or full width. |
| `padding` | Spacing number | 4 (16px) | Inner spacing. |
| `background` | Color | card | Surface color. |
| `border` | Boolean or color | Theme border | Use true for a theme border, or a color for a 1px border. |
| `status` | Object: text, icon | — | Status line. Both keys are optional; icon uses an allowed icon name. |
| `confirm` | Object: label, action | — | Optional footer button. action uses the same functionName and additionalInputs shape as onClickAction. Cancel appears before confirm. |
| `cancel` | Object: label, action | — | Optional footer button. action uses the same functionName and additionalInputs shape as onClickAction. Cancel appears before confirm. |

```jsx
<Card size="md" status={{ text: "Ready", icon: "check" }}>
  <Text value="Your results" />
</Card>
```

Card children have a fixed default gap of 12px. The card has rounded corners and a theme border even when `border` is omitted; `border={false}` does not remove that built-in border.

### Box

Flexible container with a selectable direction.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `direction` | row or column | column | Only row selects horizontal layout; other values use vertical layout. |
| `gap` | Spacing number | — | Space between children. |
| `padding` | Spacing number | — | Inner spacing. |
| `align` | start, center, end, stretch | — | Cross-axis alignment. |
| `justify` | start, center, end, between, around, evenly | — | Main-axis alignment. |
| `wrap` | Boolean | false | Allow children to wrap. |
| `background` | Color | — | Surface color. |
| `border` | Boolean or color | — | Use true for a theme border, or a color for a 1px border. |
| `radius` | none, sm, md, lg, xl, full | — | Corner radius. |
| `width` | Length | — | Width. |
| `height` | Length | — | Height. |
| `flex` | Number 0–12 | — | Grow relative to siblings; uses a zero basis. |

```jsx
<Box direction="row" gap={2}>
  <Text value="Details" />
</Box>
```

### Col

Vertical container.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `gap` | Spacing number | — | Space between children. |
| `padding` | Spacing number | — | Inner spacing. |
| `align` | start, center, end, stretch | — | Cross-axis alignment. |
| `justify` | start, center, end, between, around, evenly | — | Main-axis alignment. |
| `wrap` | Boolean | false | Allow children to wrap. |
| `background` | Color | — | Surface color. |
| `border` | Boolean or color | — | Use true for a theme border, or a color for a 1px border. |
| `radius` | none, sm, md, lg, xl, full | — | Corner radius. |
| `width` | Length | — | Width. |
| `height` | Length | — | Height. |
| `flex` | Number 0–12 | — | Grow relative to siblings; uses a zero basis. |

```jsx
<Col gap={2}>
  <Text value="Details" />
</Col>
```

### Row

Horizontal container.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `gap` | Spacing number | — | Space between children. |
| `padding` | Spacing number | — | Inner spacing. |
| `align` | start, center, end, stretch | — | Cross-axis alignment. |
| `justify` | start, center, end, between, around, evenly | — | Main-axis alignment. |
| `wrap` | Boolean | false | Allow children to wrap. |
| `background` | Color | — | Surface color. |
| `border` | Boolean or color | — | Use true for a theme border, or a color for a 1px border. |
| `radius` | none, sm, md, lg, xl, full | — | Corner radius. |
| `width` | Length | — | Width. |
| `height` | Length | — | Height. |
| `flex` | Number 0–12 | — | Grow relative to siblings; uses a zero basis. |

```jsx
<Row gap={2} align="center">
  <Text value="Details" />
</Row>
```

### Spacer

Flexible empty space.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `minSize` | Spacing number | — | Minimum width and height; grows to fill space. |

```jsx
<Spacer minSize={2} />
```

### Divider

Horizontal separator.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `spacing` | Spacing number | — | Vertical margin. |
| `flush` | Boolean | false | Stretch across the cross axis. |

```jsx
<Divider spacing={2} />
```

### ListView

Vertical list with optional progressive expansion.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `gap` | Spacing number | — | Space between children. |
| `limit` | Finite number | All children | Initial number of children, rounded down and clamped to zero. Select Show more to reveal the rest. |
| `status` | Object: text, icon | — | Status line. Both keys are optional; icon uses an allowed icon name. |

```jsx
<ListView limit={2}>
  <ListViewItem>
    <Text value="First result" />
  </ListViewItem>
</ListView>
```

### ListViewItem

Horizontal list item that can call a function.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `gap` | Spacing number | — | Space between children. |
| `align` | start, center, end, stretch | — | Cross-axis alignment. |
| `onClickAction` | Object: functionName, additionalInputs | — | Call a defined function. functionName must be a literal string; optional additionalInputs must be an object. |

```jsx
<ListViewItem gap={2}>
  <Icon name="package" />
  <Text value="Product" />
</ListViewItem>
```

## Text

### Text

Body text.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | Text, number or boolean | — | Content to display; other values display as empty text. |
| `size` | xs, sm, md, lg, xl, 2xl | sm | Text size: xs and sm are 14px; md 16px; lg 18px; xl 20px; 2xl 24px. |
| `weight` | normal, medium, semibold, bold, "400", "500", "600", "700" | normal | Font weight. |
| `color` | Color | Inherited | Text color. |
| `textAlign` | left, center, right | Inherited | Text alignment. |
| `truncate` | Boolean | false | Truncate text to one line. |
| `maxLines` | Number 1–20 | — | Clamp to this many lines, rounded down. |
| `italic` | Boolean | false | Italic text. |
| `lineThrough` | Boolean | false | Strike through text. |

```jsx
<Text value="In stock" weight="medium" />
```

### Title

Heading text.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | Text, number or boolean | — | Content to display; other values display as empty text. |
| `size` | xs, sm, md, lg, xl, 2xl | lg | Text size: xs and sm are 14px; md 16px; lg 18px; xl 20px; 2xl 24px. |
| `weight` | normal, medium, semibold, bold, "400", "500", "600", "700" | semibold | Font weight. |
| `color` | Color | Inherited | Text color. |
| `textAlign` | left, center, right | Inherited | Text alignment. |
| `truncate` | Boolean | false | Truncate text to one line. |
| `maxLines` | Number 1–20 | — | Clamp to this many lines, rounded down. |

```jsx
<Title value="Products" size="lg" />
```

### Caption

Secondary text.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | Text, number or boolean | — | Content to display; other values display as empty text. |
| `size` | xs, sm, md, lg, xl, 2xl | sm | Text size: xs and sm are 14px; md 16px; lg 18px; xl 20px; 2xl 24px. |
| `weight` | normal, medium, semibold, bold, "400", "500", "600", "700" | normal | Font weight. |
| `color` | Color | muted | Text color. |
| `textAlign` | left, center, right | Inherited | Text alignment. |
| `truncate` | Boolean | false | Truncate text to one line. |
| `maxLines` | Number 1–20 | — | Clamp to this many lines, rounded down. |

```jsx
<Caption value="Prices include tax" />
```

### Label

Short emphasized label.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `value` | Text, number or boolean | — | Content to display; other values display as empty text. |
| `size` | xs, sm, md, lg, xl, 2xl | sm | Text size: xs and sm are 14px; md 16px; lg 18px; xl 20px; 2xl 24px. |
| `weight` | normal, medium, semibold, bold, "400", "500", "600", "700" | semibold | Font weight. |

```jsx
<Label value="Delivery" />
```

## Media

### Image

Remote image.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `src` | Absolute HTTPS URL | — | Image source. HTTP and invalid URLs do not render. |
| `alt` | Text | Empty text | Alternative text. |
| `size` | sm, md, lg, xl, number or percentage | — | Named sizes are 16, 24, 40, 64px. Numbers and percentages use length rules. |
| `width` | Length | — | Width. |
| `height` | Length | — | Height. |
| `radius` | none, sm, md, lg, xl, full | md | Corner radius. |
| `fit` | cover, contain | cover | Image fit. |
| `aspectRatio` | square, video, or number greater than 0 and at most 100 | — | Width-to-height ratio; square is 1:1, video is 16:9. |
| `frame` | Boolean | false | Add a theme border. |

```jsx
<Image src="https://example.com/product.jpg" alt="Product" size={56} />
```

### Icon

Decorative icon.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | Icon name | — | An allowed icon below; unknown names do not render. |
| `size` | sm, md, lg, xl, number or percentage | 16px | Named sizes are 16, 24, 40, 64px. Numbers and percentages use length rules. |
| `color` | Color | Inherited | Text color. |

```jsx
<Icon name="shopping-bag" size="md" />
```

### Badge

Compact status label.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `label` | Text, number or boolean | — | Visible label. |
| `color` | Color | primary | Action color; outline colors its border and text, soft and ghost color text, solid colors the background. |
| `variant` | solid, soft, outline, ghost | soft | Visual treatment. |
| `size` | sm, md, lg | Base badge | sm reduces horizontal padding; lg increases padding. Text stays 12px. |
| `pill` | Boolean | false | Use fully rounded corners. |

```jsx
<Badge label="In stock" color="success" variant="soft" />
```

## Interactive

### Button

Button that calls a widget function.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `label` | Text, number or boolean | — | Visible label. |
| `onClickAction` | Object: functionName, additionalInputs | — | Call a defined function. functionName must be a literal string; optional additionalInputs must be an object. |
| `variant` | solid, soft, outline, ghost | solid | Visual treatment. |
| `color` | Color | primary | Action color; outline colors its border and text, soft and ghost color text, solid colors the background. |
| `size` | sm, md, lg | md | Button dimensions. |
| `iconStart` | Icon name | — | Icon before the label. |
| `iconEnd` | Icon name | — | Icon after the label. |
| `block` | Boolean | false | Fill the available width. |
| `pill` | Boolean | false | Use fully rounded corners. |
| `disabled` | Boolean | false | Prevent clicks. Buttons are also disabled while a function runs. |

```jsx
<Button
  label="Open product"
  onClickAction={{
    functionName: "openProduct",
    additionalInputs: { url: "https://example.com/product" },
  }}
/>
```

Structured props accept only the keys shown above. For example, define `confirmOrder` and `dismiss` in **Functions** before using this footer:

```jsx
<Card
  confirm={{ label: "Confirm", action: { functionName: "confirmOrder" } }}
  cancel={{ label: "Cancel", action: { functionName: "dismiss" } }}
>
  <Text value="Confirm your selection" />
</Card>
```

A click action requires a literal function name that exists in the widget. For example, an undefined name produces `Function "openProduct" is not defined.` Link functions accept absolute `http:` and `https:` URLs. Buttons do not accept `href`; use an **Open link** function.

### Input

Text input for single-line text, emails, or telephone numbers.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | Literal variable name | — | Variable name to write when the value changes. Required. Must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. |
| `label` | Text | — | Visible label rendered above the control. |
| `placeholder` | Text | — | Placeholder text when empty. |
| `inputType` | text, email, tel | text | HTML input type. Setting `email` enforces email pattern validation on submission. |
| `required` | Boolean | false | Prevents submission when empty. Shows "This field is required." |
| `disabled` | Boolean | false | Disables user interaction. |
| `defaultValue` | Text | — | Initial value assigned to the variable on mount if the variable is unset. |

```jsx
<Input
  name="visitorEmail"
  label="Email address"
  placeholder="alex@example.com"
  inputType="email"
  required={true}
/>
```

### Select

Dropdown selection control.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | Literal variable name | — | Variable name to write when the selected option changes. Required. Must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. |
| `label` | Text | — | Visible label rendered above the dropdown. |
| `placeholder` | Text | — | Placeholder option shown before a value is selected. |
| `options` | List of strings or `{ label, value }` | — | Available options. Can be an array literal or an expression such as `{services}` or `{slots.map((s) => ({ label: s.label, value: s.id }))}`. Up to 100 options. |
| `required` | Boolean | false | Prevents submission when empty. Shows "Choose an option." |
| `disabled` | Boolean | false | Disables user interaction. |
| `defaultValue` | Text | — | Initial value assigned to the variable on mount if the variable is unset. |

```jsx
<Select
  name="serviceType"
  label="Service"
  placeholder="Select a service"
  options={[
    { label: "Consultation (30 min)", value: "consult" },
    { label: "Product walkthrough (45 min)", value: "demo" },
  ]}
  required={true}
/>
```

### DatePicker

Calendar date selection control storing dates in `YYYY-MM-DD` format.

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | Literal variable name | — | Variable name to write when a date is selected. Required. Must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. |
| `label` | Text | — | Visible label rendered above the input. |
| `placeholder` | Text | — | Placeholder text. |
| `min` | Date string (`YYYY-MM-DD`) | — | Earliest allowed date. Values before `min` trigger "Choose a date on or after min." |
| `max` | Date string (`YYYY-MM-DD`) | — | Latest allowed date. Values after `max` trigger "Choose a date on or before max." |
| `required` | Boolean | false | Prevents submission when empty. Shows "Choose a date." |
| `disabled` | Boolean | false | Disables user interaction. |
| `defaultValue` | Date string (`YYYY-MM-DD`) | — | Initial date assigned to the variable on mount if the variable is unset. |

```jsx
<DatePicker
  name="bookingDate"
  label="Preferred date"
  min="2026-10-19"
  required={true}
/>
```

### DateTimePicker

Date and time selection control storing an ISO timestamp with the visitor's local timezone offset (for example, `2026-10-19T15:00:00-05:00`).

| Prop | Values | Default | Description |
| --- | --- | --- | --- |
| `name` | Literal variable name | — | Variable name to write when a date and time are selected. Required. Must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. |
| `label` | Text | — | Visible label rendered above the input. |
| `min` | ISO date-time string | — | Earliest allowed date and time. Shows "Choose a time on or after [time]." |
| `max` | ISO date-time string | — | Latest allowed date and time. Shows "Choose a time on or before [time]." |
| `step` | Number (1–1440) | — | Minute interval constraint. Shows "Choose a time in intervals of [step] minutes." |
| `required` | Boolean | false | Prevents submission when empty. Shows "Choose a date and time." |
| `disabled` | Boolean | false | Disables user interaction. |
| `defaultValue` | ISO date-time string | — | Initial date-time assigned to the variable on mount if unset. |

```jsx
<DateTimePicker
  name="appointmentSlot"
  label="Appointment time"
  min="2026-10-19T09:00:00-05:00"
  max="2026-10-23T17:00:00-05:00"
  step={30}
  required={true}
/>
```

Each input writes its value to the widget variable named by `name`. Read it in the widget code, such as `value={visitorEmail}`, or in a function placeholder such as `{{visitorEmail}}`. A required input must have a value before a **Send message** or **Call API** function runs.

## Shared values

### Colors

Use `primary`, `secondary`, `muted`, `default`, `foreground`, `background`, `card`, `transparent`, `success`, `error`, `destructive`, `warning`, or `info`. The renderer also accepts a `#` followed by 3–8 hexadecimal characters; use standard CSS hex lengths (3, 4, 6, or 8) for valid browser colors. Theme colors follow the chat theme and agent accent.

```jsx
<Text value="Available" color="success" />
```

### Spacing scale

Spacing props accept finite numbers. Each unit is 4px. Values are clamped to 0–12 (0–48px); fractional numbers work. Strings such as `"8px"` have no effect on spacing.

```jsx
<Row gap={2} padding={3}>
  <Text value="8px gap, 12px padding" />
</Row>
```

### Lengths

Lengths accept finite numbers from 0–1000 as pixels, or percentage strings from `"0%"` to `"100%"`, including decimals. CSS strings such as `"auto"`, `"12rem"`, and `"56px"` are not supported.

```jsx
<Box width="100%" height={80}>
  <Text value="Full width" />
</Box>
```

## Icons

Every row lists both accepted names for the same icon. Names are case-sensitive.

| PascalCase | Kebab-case |
| --- | --- |
| `ArrowDown` | `arrow-down` |
| `ArrowLeft` | `arrow-left` |
| `ArrowRight` | `arrow-right` |
| `ArrowUp` | `arrow-up` |
| `Bell` | `bell` |
| `Calendar` | `calendar` |
| `Check` | `check` |
| `CheckCircle` | `check-circle` |
| `ChevronDown` | `chevron-down` |
| `ChevronLeft` | `chevron-left` |
| `ChevronRight` | `chevron-right` |
| `ChevronUp` | `chevron-up` |
| `Clock` | `clock` |
| `Copy` | `copy` |
| `CreditCard` | `credit-card` |
| `Download` | `download` |
| `ExternalLink` | `external-link` |
| `File` | `file` |
| `Globe` | `globe` |
| `Heart` | `heart` |
| `HelpCircle` | `help-circle` |
| `Info` | `info` |
| `Link` | `link` |
| `Mail` | `mail` |
| `MapPin` | `map-pin` |
| `MessageCircle` | `message-circle` |
| `Minus` | `minus` |
| `Package` | `package` |
| `Phone` | `phone` |
| `Plus` | `plus` |
| `Search` | `search` |
| `Settings` | `settings` |
| `Shield` | `shield` |
| `ShoppingBag` | `shopping-bag` |
| `ShoppingCart` | `shopping-cart` |
| `Star` | `star` |
| `Truck` | `truck` |
| `User` | `user` |
| `X` | `x` |
| `XCircle` | `xcircle` |
| `TriangleAlert` | `triangle-alert` |

Aliases: `success`, `error`, `warning`, `external`, `close`, `add`, `remove`, `back`, `forward`.

```jsx
<Icon name="success" color="success" />
```