Component reference

Widgets use layout, text, media, and interactive components. Use this reference to choose components and their supported props.

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.

<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.

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

Col

Vertical container.

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

Row

Horizontal container.

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

Spacer

Flexible empty space.

<Spacer minSize={2} />

Divider

Horizontal separator.

<Divider spacing={2} />

ListView

Vertical list with optional progressive expansion.

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

ListViewItem

Horizontal list item that can call a function.

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

Text

Text

Body text.

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

Title

Heading text.

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

Caption

Secondary text.

<Caption value="Prices include tax" />

Label

Short emphasized label.

<Label value="Delivery" />

Media

Image

Remote image.

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

Icon

Decorative icon.

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

Badge

Compact status label.

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

Interactive

Button

Button that calls a widget function.

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

<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.

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

Select

Dropdown selection control.

<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.

<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).

<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.

<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.

<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.

<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.

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

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