Skip to content

widgets

Card

Bases: _WidgetRootBuilder

Versatile container used for structuring widget content.

Source code in chatkit/widgets.py
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
class Card(_WidgetRootBuilder):
    """Versatile container used for structuring widget content."""

    type: Literal["Card"] = Field(default="Card", frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
    asForm: bool | None = None
    """Treat the card as an HTML form so confirm/cancel capture form data."""
    children: list[_WidgetChild]
    """Child components rendered inside the card."""
    background: str | ThemeColor | None = None
    """Background color; accepts background color token, a primitive color token, a CSS string, or theme-aware `{ light, dark }`.

    Valid tokens: `surface` `surface-secondary` `surface-tertiary` `surface-elevated` `surface-elevated-secondary`

    Primitive color token: e.g. `red-100`, `blue-900`, `gray-500`
    """
    border: int | float | Border | Borders | None = None
    """Card border as a thickness in px, a border style, or per-edge settings."""
    size: Literal["sm", "md", "lg", "full"] | None = None
    """Visual size of the card; accepts a size token. No preset default is documented."""
    padding: float | str | Spacing | None = None
    """Inner spacing of the card; spacing unit, CSS string, or padding object."""
    status: WidgetStatus | None = None
    """Optional status header displayed above the card."""
    collapsed: bool | None = None
    """Collapse card body after the main action has completed."""
    confirm: CardAction | None = None
    """Confirmation action button shown in the card footer."""
    cancel: CardAction | None = None
    """Cancel action button shown in the card footer."""
    theme: Literal["light", "dark"] | None = None
    """Force light or dark theme for this subtree."""

asForm class-attribute instance-attribute

asForm: bool | None = None

Treat the card as an HTML form so confirm/cancel capture form data.

children instance-attribute

children: list[_WidgetChild]

Child components rendered inside the card.

background class-attribute instance-attribute

background: str | ThemeColor | None = None

Background color; accepts background color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

Valid tokens: surface surface-secondary surface-tertiary surface-elevated surface-elevated-secondary

Primitive color token: e.g. red-100, blue-900, gray-500

border class-attribute instance-attribute

border: int | float | Border | Borders | None = None

Card border as a thickness in px, a border style, or per-edge settings.

size class-attribute instance-attribute

size: Literal['sm', 'md', 'lg', 'full'] | None = None

Visual size of the card; accepts a size token. No preset default is documented.

padding class-attribute instance-attribute

padding: float | str | Spacing | None = None

Inner spacing of the card; spacing unit, CSS string, or padding object.

status class-attribute instance-attribute

status: WidgetStatus | None = None

Optional status header displayed above the card.

collapsed class-attribute instance-attribute

collapsed: bool | None = None

Collapse card body after the main action has completed.

confirm class-attribute instance-attribute

confirm: CardAction | None = None

Confirmation action button shown in the card footer.

cancel class-attribute instance-attribute

cancel: CardAction | None = None

Cancel action button shown in the card footer.

theme class-attribute instance-attribute

theme: Literal['light', 'dark'] | None = None

Force light or dark theme for this subtree.

ListView

Bases: _WidgetRootBuilder

Container component for rendering collections of list items.

Source code in chatkit/widgets.py
219
220
221
222
223
224
225
226
227
228
229
230
class ListView(_WidgetRootBuilder):
    """Container component for rendering collections of list items."""

    type: Literal["ListView"] = Field(default="ListView", frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
    children: list[ListViewItem]
    """Items to render in the list."""
    limit: int | Literal["auto"] | None = None
    """Max number of items to show before a "Show more" control."""
    status: WidgetStatus | None = None
    """Optional status header displayed above the list."""
    theme: Literal["light", "dark"] | None = None
    """Force light or dark theme for this subtree."""

children instance-attribute

children: list[ListViewItem]

Items to render in the list.

limit class-attribute instance-attribute

limit: int | Literal['auto'] | None = None

Max number of items to show before a "Show more" control.

status class-attribute instance-attribute

status: WidgetStatus | None = None

Optional status header displayed above the list.

theme class-attribute instance-attribute

theme: Literal['light', 'dark'] | None = None

Force light or dark theme for this subtree.

ListViewItem

Bases: WidgetComponentBase

Single row inside a ListView component.

Source code in chatkit/widgets.py
205
206
207
208
209
210
211
212
213
214
215
216
class ListViewItem(WidgetComponentBase):
    """Single row inside a ``ListView`` component."""

    type: Literal["ListViewItem"] = Field(default="ListViewItem", frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
    children: list[_WidgetChild]
    """Content for the list item."""
    onClickAction: actions.ActionConfig | None = None
    """Optional action triggered when the list item is clicked."""
    gap: int | str | None = None
    """Gap between children within the list item; spacing unit or CSS string."""
    align: Alignment | None = None
    """Y-axis alignment for content within the list item."""

children instance-attribute

children: list[_WidgetChild]

Content for the list item.

onClickAction class-attribute instance-attribute

onClickAction: ActionConfig | None = None

Optional action triggered when the list item is clicked.

gap class-attribute instance-attribute

gap: int | str | None = None

Gap between children within the list item; spacing unit or CSS string.

align class-attribute instance-attribute

align: Alignment | None = None

Y-axis alignment for content within the list item.

Text

Bases: WidgetComponentBase

Widget rendering plain text with typography controls.

Source code in chatkit/widgets.py
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
class Text(WidgetComponentBase):
    """Widget rendering plain text with typography controls."""

    type: Literal["Text"] = Field(default="Text", frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
    value: str
    """Text content to display."""
    streaming: bool | None = None
    """Enables streaming-friendly transitions for incremental updates."""
    italic: bool | None = None
    """Render text in italic style."""
    lineThrough: bool | None = None
    """Render text with a line-through decoration."""
    color: str | ThemeColor | None = None
    """
    Text color; accepts a text color token, a primitive color token, a CSS color string, or a theme-aware `{ light, dark }`.

    Text color tokens: `prose` `primary` `emphasis` `secondary` `tertiary` `success` `warning` `danger`

    Primitive color token: e.g. `red-100`, `blue-900`, `gray-500`
    """
    weight: Literal["normal", "medium", "semibold", "bold"] | None = None
    """Font weight; accepts a font weight token."""
    width: float | str | None = None
    """Constrain the text container width; px or CSS string."""
    size: TextSize | None = None
    """Size of the text; accepts a text size token."""
    textAlign: TextAlign | None = None
    """Horizontal text alignment."""
    truncate: bool | None = None
    """Truncate overflow with ellipsis."""
    minLines: int | None = None
    """Reserve space for a minimum number of lines."""
    maxLines: int | None = None
    """Limit text to a maximum number of lines (line clamp)."""
    editable: Literal[False] | EditableProps | None = None
    """Enable inline editing for this text node."""

value instance-attribute

value: str

Text content to display.

streaming class-attribute instance-attribute

streaming: bool | None = None

Enables streaming-friendly transitions for incremental updates.

italic class-attribute instance-attribute

italic: bool | None = None

Render text in italic style.

lineThrough class-attribute instance-attribute

lineThrough: bool | None = None

Render text with a line-through decoration.

color class-attribute instance-attribute

color: str | ThemeColor | None = None

Text color; accepts a text color token, a primitive color token, a CSS color string, or a theme-aware { light, dark }.

Text color tokens: prose primary emphasis secondary tertiary success warning danger

Primitive color token: e.g. red-100, blue-900, gray-500

weight class-attribute instance-attribute

weight: Literal['normal', 'medium', 'semibold', 'bold'] | None = None

Font weight; accepts a font weight token.

width class-attribute instance-attribute

width: float | str | None = None

Constrain the text container width; px or CSS string.

size class-attribute instance-attribute

size: TextSize | None = None

Size of the text; accepts a text size token.

textAlign class-attribute instance-attribute

textAlign: TextAlign | None = None

Horizontal text alignment.

truncate class-attribute instance-attribute

truncate: bool | None = None

Truncate overflow with ellipsis.

minLines class-attribute instance-attribute

minLines: int | None = None

Reserve space for a minimum number of lines.

maxLines class-attribute instance-attribute

maxLines: int | None = None

Limit text to a maximum number of lines (line clamp).

editable class-attribute instance-attribute

editable: Literal[False] | EditableProps | None = None

Enable inline editing for this text node.

Button

Bases: WidgetComponentBase

Button component optionally wired to an action.

Source code in chatkit/widgets.py
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
class Button(WidgetComponentBase):
    """Button component optionally wired to an action."""

    type: Literal["Button"] = Field(default="Button", frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
    submit: bool | None = None
    """Configure the button as a submit button for the nearest form."""
    label: str | None = None
    """Text to display inside the button."""
    onClickAction: actions.ActionConfig | None = None
    """Action dispatched on click."""
    iconStart: icons.IconName | None = None
    """Icon shown before the label; can be used for icon-only buttons."""
    iconEnd: icons.IconName | None = None
    """Optional icon shown after the label."""
    style: Literal["primary", "secondary"] | None = None
    """Convenience preset for button style."""
    iconSize: Literal["sm", "md", "lg", "xl", "2xl"] | None = None
    """Controls the size of icons within the button; accepts an icon size token."""
    color: (
        Literal[
            "primary",
            "secondary",
            "info",
            "discovery",
            "success",
            "caution",
            "warning",
            "danger",
        ]
        | None
    ) = None
    """Color of the button; accepts a button color token."""
    variant: ControlVariant | None = None
    """Visual variant of the button; accepts a control variant token."""
    size: ControlSize | None = None
    """Controls the overall size of the button."""
    pill: bool | None = None
    """Determines if the button should be fully rounded (pill)."""
    uniform: bool | None = None
    """Determines if the button should have matching width and height."""
    block: bool | None = None
    """Extend the button to 100% of the available width."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""

submit class-attribute instance-attribute

submit: bool | None = None

Configure the button as a submit button for the nearest form.

label class-attribute instance-attribute

label: str | None = None

Text to display inside the button.

onClickAction class-attribute instance-attribute

onClickAction: ActionConfig | None = None

Action dispatched on click.

iconStart class-attribute instance-attribute

iconStart: IconName | None = None

Icon shown before the label; can be used for icon-only buttons.

iconEnd class-attribute instance-attribute

iconEnd: IconName | None = None

Optional icon shown after the label.

style class-attribute instance-attribute

style: Literal['primary', 'secondary'] | None = None

Convenience preset for button style.

iconSize class-attribute instance-attribute

iconSize: Literal['sm', 'md', 'lg', 'xl', '2xl'] | None = None

Controls the size of icons within the button; accepts an icon size token.

color class-attribute instance-attribute

color: Literal['primary', 'secondary', 'info', 'discovery', 'success', 'caution', 'warning', 'danger'] | None = None

Color of the button; accepts a button color token.

variant class-attribute instance-attribute

variant: ControlVariant | None = None

Visual variant of the button; accepts a control variant token.

size class-attribute instance-attribute

size: ControlSize | None = None

Controls the overall size of the button.

pill class-attribute instance-attribute

pill: bool | None = None

Determines if the button should be fully rounded (pill).

uniform class-attribute instance-attribute

uniform: bool | None = None

Determines if the button should have matching width and height.

block class-attribute instance-attribute

block: bool | None = None

Extend the button to 100% of the available width.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.