widgets

RadiusValue module-attribute

RadiusValue = Literal[
    "2xs",
    "xs",
    "sm",
    "md",
    "lg",
    "xl",
    "2xl",
    "3xl",
    "4xl",
    "full",
    "100%",
    "none",
]

Allowed corner radius tokens.

TextAlign module-attribute

TextAlign = Literal['start', 'center', 'end']

Horizontal text alignment options.

TextSize module-attribute

TextSize = Literal['xs', 'sm', 'md', 'lg', 'xl']

Body text size tokens.

IconSize module-attribute

IconSize = Literal[
    "xs", "sm", "md", "lg", "xl", "2xl", "3xl"
]

Icon size tokens.

TitleSize module-attribute

TitleSize = Literal[
    "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl"
]

Title text size tokens.

CaptionSize module-attribute

CaptionSize = Literal['sm', 'md', 'lg']

Caption text size tokens.

Alignment module-attribute

Alignment = Literal[
    "start", "center", "end", "baseline", "stretch"
]

Flexbox alignment options.

Justification module-attribute

Justification = Literal[
    "start",
    "center",
    "end",
    "between",
    "around",
    "evenly",
    "stretch",
]

Flexbox justification options.

ControlVariant module-attribute

ControlVariant = Literal[
    "solid", "soft", "outline", "ghost"
]

Button and input style variants.

ControlSize module-attribute

ControlSize = Literal[
    "3xs", "2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl"
]

Button and input size variants.

WidgetStatus module-attribute

WidgetStatus = (
    WidgetStatusWithFavicon | WidgetStatusWithIcon
)

Union for representing widget status messaging.

CurveType module-attribute

CurveType = Literal[
    "basis",
    "basisClosed",
    "basisOpen",
    "bumpX",
    "bumpY",
    "bump",
    "linear",
    "linearClosed",
    "natural",
    "monotoneX",
    "monotoneY",
    "monotone",
    "step",
    "stepBefore",
    "stepAfter",
]

Interpolation curve types for area and line series.

Series module-attribute

Series = Annotated[
    BarSeries | AreaSeries | LineSeries,
    Field(discriminator="type"),
]

Union of all supported chart series types.

WidgetComponent module-attribute

WidgetComponent = Annotated[
    Text
    | Title
    | Caption
    | Chart
    | Badge
    | Markdown
    | Box
    | Row
    | Col
    | Divider
    | Icon
    | Image
    | ListViewItem
    | Button
    | Checkbox
    | Spacer
    | Select
    | DatePicker
    | Form
    | Input
    | Label
    | RadioGroup
    | Textarea
    | Transition,
    Field(discriminator="type"),
]

Union of all renderable widget components.

WidgetIcon module-attribute

WidgetIcon = Literal[
    "agent",
    "analytics",
    "atom",
    "batch",
    "bolt",
    "book-open",
    "book-clock",
    "book-closed",
    "bug",
    "calendar",
    "chart",
    "check",
    "check-circle",
    "check-circle-filled",
    "chevron-left",
    "chevron-right",
    "circle-question",
    "compass",
    "confetti",
    "cube",
    "desktop",
    "document",
    "dot",
    "dots-horizontal",
    "dots-vertical",
    "empty-circle",
    "external-link",
    "globe",
    "keys",
    "lab",
    "images",
    "info",
    "lifesaver",
    "lightbulb",
    "mail",
    "map-pin",
    "maps",
    "mobile",
    "name",
    "notebook",
    "notebook-pencil",
    "page-blank",
    "phone",
    "play",
    "plus",
    "profile",
    "profile-card",
    "reload",
    "star",
    "star-filled",
    "search",
    "sparkle",
    "sparkle-double",
    "square-code",
    "square-image",
    "square-text",
    "suitcase",
    "settings-slider",
    "user",
    "wreath",
    "write",
    "write-alt",
    "write-alt2",
]

Icon names accepted by widgets that render icons.

ThemeColor

Bases: TypedDict

Color values for light and dark themes.

Source code in chatkit/widgets.py

class ThemeColor(TypedDict):
    """Color values for light and dark themes."""

    dark: str
    """Color to use when the theme is dark."""
    light: str
    """Color to use when the theme is light."""

dark instance-attribute

dark: str

Color to use when the theme is dark.

light instance-attribute

light: str

Color to use when the theme is light.

Spacing

Bases: TypedDict

Shorthand spacing values applied to a widget.

Source code in chatkit/widgets.py

class Spacing(TypedDict):
    """Shorthand spacing values applied to a widget."""

    top: NotRequired[float | str]
    """Top spacing; accepts a spacing unit or CSS string."""
    right: NotRequired[float | str]
    """Right spacing; accepts a spacing unit or CSS string."""
    bottom: NotRequired[float | str]
    """Bottom spacing; accepts a spacing unit or CSS string."""
    left: NotRequired[float | str]
    """Left spacing; accepts a spacing unit or CSS string."""
    x: NotRequired[float | str]
    """Horizontal spacing; accepts a spacing unit or CSS string."""
    y: NotRequired[float | str]
    """Vertical spacing; accepts a spacing unit or CSS string."""

top instance-attribute

top: NotRequired[float | str]

Top spacing; accepts a spacing unit or CSS string.

right instance-attribute

right: NotRequired[float | str]

Right spacing; accepts a spacing unit or CSS string.

bottom instance-attribute

bottom: NotRequired[float | str]

Bottom spacing; accepts a spacing unit or CSS string.

left instance-attribute

left: NotRequired[float | str]

Left spacing; accepts a spacing unit or CSS string.

x instance-attribute

x: NotRequired[float | str]

Horizontal spacing; accepts a spacing unit or CSS string.

y instance-attribute

y: NotRequired[float | str]

Vertical spacing; accepts a spacing unit or CSS string.

Border

Bases: TypedDict

Border style definition for an edge.

Source code in chatkit/widgets.py

class Border(TypedDict):
    """Border style definition for an edge."""

    size: int
    """Thickness of the border in px."""
    color: NotRequired[str | ThemeColor]
    """Border color; accepts border color token, a primitive color token, a CSS string, or theme-aware `{ light, dark }`.

    Valid tokens: `default` `subtle` `strong`

    Primitive color token: e.g. `red-100`, `blue-900`, `gray-500`
    """
    style: NotRequired[
        Literal[
            "solid", "dashed", "dotted", "double", "groove", "ridge", "inset", "outset"
        ]
    ]
    """Border line style."""

size instance-attribute

size: int

Thickness of the border in px.

color instance-attribute

color: NotRequired[str | ThemeColor]

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

Valid tokens: default subtle strong

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

style instance-attribute

style: NotRequired[
    Literal[
        "solid",
        "dashed",
        "dotted",
        "double",
        "groove",
        "ridge",
        "inset",
        "outset",
    ]
]

Border line style.

Borders

Bases: TypedDict

Composite border configuration applied across edges.

Source code in chatkit/widgets.py

class Borders(TypedDict):
    """Composite border configuration applied across edges."""

    top: NotRequired[int | Border]
    """Top border or thickness in px."""
    right: NotRequired[int | Border]
    """Right border or thickness in px."""
    bottom: NotRequired[int | Border]
    """Bottom border or thickness in px."""
    left: NotRequired[int | Border]
    """Left border or thickness in px."""
    x: NotRequired[int | Border]
    """Horizontal borders or thickness in px."""
    y: NotRequired[int | Border]
    """Vertical borders or thickness in px."""

top instance-attribute

top: NotRequired[int | Border]

Top border or thickness in px.

right instance-attribute

right: NotRequired[int | Border]

Right border or thickness in px.

bottom instance-attribute

bottom: NotRequired[int | Border]

Bottom border or thickness in px.

left instance-attribute

left: NotRequired[int | Border]

Left border or thickness in px.

x instance-attribute

x: NotRequired[int | Border]

Horizontal borders or thickness in px.

y instance-attribute

y: NotRequired[int | Border]

Vertical borders or thickness in px.

MinMax

Bases: TypedDict

Integer minimum/maximum bounds.

Source code in chatkit/widgets.py

class MinMax(TypedDict):
    """Integer minimum/maximum bounds."""

    min: NotRequired[int]
    """Minimum value (inclusive)."""
    max: NotRequired[int]
    """Maximum value (inclusive)."""

min instance-attribute

min: NotRequired[int]

Minimum value (inclusive).

max instance-attribute

max: NotRequired[int]

Maximum value (inclusive).

EditableProps

Bases: TypedDict

Editable field options for text widgets.

Source code in chatkit/widgets.py

class EditableProps(TypedDict):
    """Editable field options for text widgets."""

    name: str
    """The name of the form control field used when submitting forms."""
    autoFocus: NotRequired[bool]
    """Autofocus the editable input when it appears."""
    autoSelect: NotRequired[bool]
    """Select all text on focus."""
    autoComplete: NotRequired[str]
    """Native autocomplete hint for the input."""
    allowAutofillExtensions: NotRequired[bool]
    """Allow browser password/autofill extensions."""
    pattern: NotRequired[str]
    """Regex pattern for input validation."""
    placeholder: NotRequired[str]
    """Placeholder text for the editable input."""
    required: NotRequired[bool]
    """Mark the editable input as required."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

autoFocus instance-attribute

autoFocus: NotRequired[bool]

Autofocus the editable input when it appears.

autoSelect instance-attribute

autoSelect: NotRequired[bool]

Select all text on focus.

autoComplete instance-attribute

autoComplete: NotRequired[str]

Native autocomplete hint for the input.

allowAutofillExtensions instance-attribute

allowAutofillExtensions: NotRequired[bool]

Allow browser password/autofill extensions.

pattern instance-attribute

pattern: NotRequired[str]

Regex pattern for input validation.

placeholder instance-attribute

placeholder: NotRequired[str]

Placeholder text for the editable input.

required instance-attribute

required: NotRequired[bool]

Mark the editable input as required.

WidgetComponentBase

Bases: BaseModel

Base Pydantic model for all ChatKit widget components.

Source code in chatkit/widgets.py

class WidgetComponentBase(BaseModel):
    """Base Pydantic model for all ChatKit widget components."""

    model_config = ConfigDict(serialize_by_alias=True)

    key: str | None = None
    id: str | None = None
    type: str = Field(...)

    # For nested model dumps (e.g. if Widget is not the top-level model)
    @model_serializer(mode="wrap")
    def serialize(self, next_):
        dumped = next_(self)
        # Recursively filter out None values when serialized.
        # Do this explicitly instead of overriding model_dump_json and model_dump;
        # the overrides will not be invoked unless the widget is the top-level model.
        dumped = _drop_none(dumped)
        # include type even when exlude_defaults is True
        if isinstance(dumped, dict):
            dumped["type"] = self.type

        return dumped

WidgetStatusWithFavicon

Bases: TypedDict

Widget status representation using a favicon.

Source code in chatkit/widgets.py

class WidgetStatusWithFavicon(TypedDict):
    """Widget status representation using a favicon."""

    text: str
    """Status text to display."""
    favicon: NotRequired[str]
    """URL of a favicon to render at the start of the status."""
    frame: NotRequired[bool]
    """Show a frame around the favicon for contrast."""

text instance-attribute

text: str

Status text to display.

favicon instance-attribute

favicon: NotRequired[str]

URL of a favicon to render at the start of the status.

frame instance-attribute

frame: NotRequired[bool]

Show a frame around the favicon for contrast.

WidgetStatusWithIcon

Bases: TypedDict

Widget status representation using an icon.

Source code in chatkit/widgets.py

class WidgetStatusWithIcon(TypedDict):
    """Widget status representation using an icon."""

    text: str
    """Status text to display."""
    icon: NotRequired[WidgetIcon]
    """Icon to render at the start of the status."""

text instance-attribute

text: str

Status text to display.

icon instance-attribute

icon: NotRequired[WidgetIcon]

Icon to render at the start of the status.

ListViewItem

Bases: WidgetComponentBase

Single row inside a ListView component.

Source code in chatkit/widgets.py

class ListViewItem(WidgetComponentBase):
    """Single row inside a ``ListView`` component."""

    type: Literal["ListViewItem"] = Field(default="ListViewItem", frozen=True)  # pyright: ignore
    children: list["WidgetComponent"]
    """Content for the list item."""
    onClickAction: 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['WidgetComponent']

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.

ListView

Bases: WidgetComponentBase

Container component for rendering collections of list items.

Source code in chatkit/widgets.py

class ListView(WidgetComponentBase):
    """Container component for rendering collections of list items."""

    type: Literal["ListView"] = Field(default="ListView", frozen=True)  # pyright: ignore
    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.

CardAction

Bases: TypedDict

Configuration for confirm/cancel actions within a card.

Source code in chatkit/widgets.py

class CardAction(TypedDict):
    """Configuration for confirm/cancel actions within a card."""

    label: str
    """Button label shown in the card footer."""
    action: ActionConfig
    """Declarative action dispatched to the host application."""

label instance-attribute

label: str

Button label shown in the card footer.

action instance-attribute

action: ActionConfig

Declarative action dispatched to the host application.

Card

Bases: WidgetComponentBase

Versatile container used for structuring widget content.

Source code in chatkit/widgets.py

class Card(WidgetComponentBase):
    """Versatile container used for structuring widget content."""

    type: Literal["Card"] = Field(default="Card", frozen=True)  # pyright: ignore
    asForm: bool | None = None
    """Treat the card as an HTML form so confirm/cancel capture form data."""
    children: list["WidgetComponent"]
    """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`
    """
    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['WidgetComponent']

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

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.

Markdown

Bases: WidgetComponentBase

Widget rendering Markdown content, optionally streamed.

Source code in chatkit/widgets.py

class Markdown(WidgetComponentBase):
    """Widget rendering Markdown content, optionally streamed."""

    type: Literal["Markdown"] = Field(default="Markdown", frozen=True)  # pyright: ignore
    value: str
    """Markdown source string to render."""
    streaming: bool | None = None
    """Applies streaming-friendly transitions for incremental updates."""

value instance-attribute

value: str

Markdown source string to render.

streaming class-attribute instance-attribute

streaming: bool | None = None

Applies streaming-friendly transitions for incremental updates.

Text

Bases: WidgetComponentBase

Widget rendering plain text with typography controls.

Source code in chatkit/widgets.py

class Text(WidgetComponentBase):
    """Widget rendering plain text with typography controls."""

    type: Literal["Text"] = Field(default="Text", frozen=True)  # pyright: ignore
    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.

Title

Bases: WidgetComponentBase

Widget rendering prominent headline text.

Source code in chatkit/widgets.py

class Title(WidgetComponentBase):
    """Widget rendering prominent headline text."""

    type: Literal["Title"] = Field(default="Title", frozen=True)  # pyright: ignore
    value: str
    """Text content to display."""
    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."""
    size: TitleSize | None = None
    """Size of the title text; accepts a title size token."""
    textAlign: TextAlign | None = None
    """Horizontal text alignment."""
    truncate: bool | None = None
    """Truncate overflow with ellipsis."""
    maxLines: int | None = None
    """Limit text to a maximum number of lines (line clamp)."""

value instance-attribute

value: str

Text content to display.

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.

size class-attribute instance-attribute

size: TitleSize | None = None

Size of the title text; accepts a title 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.

maxLines class-attribute instance-attribute

maxLines: int | None = None

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

Caption

Bases: WidgetComponentBase

Widget rendering supporting caption text.

Source code in chatkit/widgets.py

class Caption(WidgetComponentBase):
    """Widget rendering supporting caption text."""

    type: Literal["Caption"] = Field(default="Caption", frozen=True)  # pyright: ignore
    value: str
    """Text content to display."""
    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."""
    size: CaptionSize | None = None
    """Size of the caption text; accepts a caption size token."""
    textAlign: TextAlign | None = None
    """Horizontal text alignment."""
    truncate: bool | None = None
    """Truncate overflow with ellipsis."""
    maxLines: int | None = None
    """Limit text to a maximum number of lines (line clamp)."""

value instance-attribute

value: str

Text content to display.

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.

size class-attribute instance-attribute

size: CaptionSize | None = None

Size of the caption text; accepts a caption 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.

maxLines class-attribute instance-attribute

maxLines: int | None = None

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

Badge

Bases: WidgetComponentBase

Small badge indicating status or categorization.

Source code in chatkit/widgets.py

class Badge(WidgetComponentBase):
    """Small badge indicating status or categorization."""

    type: Literal["Badge"] = Field(default="Badge", frozen=True)  # pyright: ignore
    label: str
    """Text to display inside the badge."""
    color: (
        Literal["secondary", "success", "danger", "warning", "info", "discovery"] | None
    ) = None
    """Color of the badge; accepts a badge color token."""
    variant: Literal["solid", "soft", "outline"] | None = None
    """Visual style of the badge."""
    size: Literal["sm", "md", "lg"] | None = None
    """Size of the badge."""
    pill: bool | None = None
    """Determines if the badge should be fully rounded (pill)."""

label instance-attribute

label: str

Text to display inside the badge.

color class-attribute instance-attribute

color: (
    Literal[
        "secondary",
        "success",
        "danger",
        "warning",
        "info",
        "discovery",
    ]
    | None
) = None

Color of the badge; accepts a badge color token.

variant class-attribute instance-attribute

variant: Literal['solid', 'soft', 'outline'] | None = None

Visual style of the badge.

size class-attribute instance-attribute

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

Size of the badge.

pill class-attribute instance-attribute

pill: bool | None = None

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

BoxBase

Bases: BaseModel

Shared layout props for flexible container widgets.

Source code in chatkit/widgets.py

class BoxBase(BaseModel):
    """Shared layout props for flexible container widgets."""

    children: list["WidgetComponent"] | None = None
    """Child components to render inside the container."""
    align: Alignment | None = None
    """Cross-axis alignment of children."""
    justify: Justification | None = None
    """Main-axis distribution of children."""
    wrap: Literal["nowrap", "wrap", "wrap-reverse"] | None = None
    """Wrap behavior for flex items."""
    flex: int | str | None = None
    """Flex growth/shrink factor."""
    gap: int | str | None = None
    """Gap between direct children; spacing unit or CSS string."""
    height: float | str | None = None
    """Explicit height; px or CSS string."""
    width: float | str | None = None
    """Explicit width; px or CSS string."""
    size: float | str | None = None
    """Shorthand to set both width and height; px or CSS string."""
    minHeight: int | str | None = None
    """Minimum height; px or CSS string."""
    minWidth: int | str | None = None
    """Minimum width; px or CSS string."""
    minSize: int | str | None = None
    """Shorthand to set both minWidth and minHeight; px or CSS string."""
    maxHeight: int | str | None = None
    """Maximum height; px or CSS string."""
    maxWidth: int | str | None = None
    """Maximum width; px or CSS string."""
    maxSize: int | str | None = None
    """Shorthand to set both maxWidth and maxHeight; px or CSS string."""
    padding: float | str | Spacing | None = None
    """Inner padding; spacing unit, CSS string, or padding object."""
    margin: float | str | Spacing | None = None
    """Outer margin; spacing unit, CSS string, or margin object."""
    border: int | Border | Borders | None = None
    """Border applied to the container; px or border object/shorthand."""
    radius: RadiusValue | None = None
    """Border radius; accepts a radius token."""
    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`
    """
    aspectRatio: float | str | None = None
    """Aspect ratio of the box (e.g., 16/9); number or CSS string."""

children class-attribute instance-attribute

children: list['WidgetComponent'] | None = None

Child components to render inside the container.

align class-attribute instance-attribute

align: Alignment | None = None

Cross-axis alignment of children.

justify class-attribute instance-attribute

justify: Justification | None = None

Main-axis distribution of children.

wrap class-attribute instance-attribute

wrap: Literal["nowrap", "wrap", "wrap-reverse"] | None = (
    None
)

Wrap behavior for flex items.

flex class-attribute instance-attribute

flex: int | str | None = None

Flex growth/shrink factor.

gap class-attribute instance-attribute

gap: int | str | None = None

Gap between direct children; spacing unit or CSS string.

height class-attribute instance-attribute

height: float | str | None = None

Explicit height; px or CSS string.

width class-attribute instance-attribute

width: float | str | None = None

Explicit width; px or CSS string.

size class-attribute instance-attribute

size: float | str | None = None

Shorthand to set both width and height; px or CSS string.

minHeight class-attribute instance-attribute

minHeight: int | str | None = None

Minimum height; px or CSS string.

minWidth class-attribute instance-attribute

minWidth: int | str | None = None

Minimum width; px or CSS string.

minSize class-attribute instance-attribute

minSize: int | str | None = None

Shorthand to set both minWidth and minHeight; px or CSS string.

maxHeight class-attribute instance-attribute

maxHeight: int | str | None = None

Maximum height; px or CSS string.

maxWidth class-attribute instance-attribute

maxWidth: int | str | None = None

Maximum width; px or CSS string.

maxSize class-attribute instance-attribute

maxSize: int | str | None = None

Shorthand to set both maxWidth and maxHeight; px or CSS string.

padding class-attribute instance-attribute

padding: float | str | Spacing | None = None

Inner padding; spacing unit, CSS string, or padding object.

margin class-attribute instance-attribute

margin: float | str | Spacing | None = None

Outer margin; spacing unit, CSS string, or margin object.

border class-attribute instance-attribute

border: int | Border | Borders | None = None

Border applied to the container; px or border object/shorthand.

radius class-attribute instance-attribute

radius: RadiusValue | None = None

Border radius; accepts a radius token.

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

aspectRatio class-attribute instance-attribute

aspectRatio: float | str | None = None

Aspect ratio of the box (e.g., 16/9); number or CSS string.

Box

Bases: WidgetComponentBase, BoxBase

Generic flex container with direction control.

Source code in chatkit/widgets.py

class Box(WidgetComponentBase, BoxBase):
    """Generic flex container with direction control."""

    type: Literal["Box"] = Field(default="Box", frozen=True)  # pyright: ignore
    direction: Literal["row", "col"] | None = None
    """Flex direction for content within this container."""

direction class-attribute instance-attribute

direction: Literal['row', 'col'] | None = None

Flex direction for content within this container.

Row

Bases: WidgetComponentBase, BoxBase

Horizontal flex container.

Source code in chatkit/widgets.py

class Row(WidgetComponentBase, BoxBase):
    """Horizontal flex container."""

    type: Literal["Row"] = Field(default="Row", frozen=True)  # pyright: ignore

Col

Bases: WidgetComponentBase, BoxBase

Vertical flex container.

Source code in chatkit/widgets.py

class Col(WidgetComponentBase, BoxBase):
    """Vertical flex container."""

    type: Literal["Col"] = Field(default="Col", frozen=True)  # pyright: ignore

Form

Bases: WidgetComponentBase, BoxBase

Form wrapper capable of submitting onSubmitAction.

Source code in chatkit/widgets.py

class Form(WidgetComponentBase, BoxBase):
    """Form wrapper capable of submitting ``onSubmitAction``."""

    type: Literal["Form"] = Field(default="Form", frozen=True)  # pyright: ignore
    onSubmitAction: ActionConfig | None = None
    """Action dispatched when the form is submitted."""
    direction: Literal["row", "col"] | None = None
    """Flex direction for laying out form children."""

onSubmitAction class-attribute instance-attribute

onSubmitAction: ActionConfig | None = None

Action dispatched when the form is submitted.

direction class-attribute instance-attribute

direction: Literal['row', 'col'] | None = None

Flex direction for laying out form children.

Divider

Bases: WidgetComponentBase

Visual divider separating content sections.

Source code in chatkit/widgets.py

class Divider(WidgetComponentBase):
    """Visual divider separating content sections."""

    type: Literal["Divider"] = Field(default="Divider", frozen=True)  # pyright: ignore
    color: str | ThemeColor | None = None
    """Divider color; accepts border color token, a primitive color token, a CSS string, or theme-aware `{ light, dark }`.

    Valid tokens: `default` `subtle` `strong`

    Primitive color token: e.g. `red-100`, `blue-900`, `gray-500`
    """
    size: int | str | None = None
    """Thickness of the divider line; px or CSS string."""
    spacing: int | str | None = None
    """Outer spacing above and below the divider; spacing unit or CSS string."""
    flush: bool | None = None
    """Flush the divider to the container edge, removing surrounding padding."""

color class-attribute instance-attribute

color: str | ThemeColor | None = None

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

Valid tokens: default subtle strong

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

size class-attribute instance-attribute

size: int | str | None = None

Thickness of the divider line; px or CSS string.

spacing class-attribute instance-attribute

spacing: int | str | None = None

Outer spacing above and below the divider; spacing unit or CSS string.

flush class-attribute instance-attribute

flush: bool | None = None

Flush the divider to the container edge, removing surrounding padding.

Icon

Bases: WidgetComponentBase

Icon component referencing a built-in icon name.

Source code in chatkit/widgets.py

class Icon(WidgetComponentBase):
    """Icon component referencing a built-in icon name."""

    type: Literal["Icon"] = Field(default="Icon", frozen=True)  # pyright: ignore
    name: WidgetIcon
    """Name of the icon to display."""
    color: str | ThemeColor | None = None
    """
    Icon 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`
    """
    size: IconSize | None = None
    """Size of the icon; accepts an icon size token."""

name instance-attribute

name: WidgetIcon

Name of the icon to display.

color class-attribute instance-attribute

color: str | ThemeColor | None = None

Icon 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

size class-attribute instance-attribute

size: IconSize | None = None

Size of the icon; accepts an icon size token.

Image

Bases: WidgetComponentBase

Image component with sizing and fitting controls.

Source code in chatkit/widgets.py

class Image(WidgetComponentBase):
    """Image component with sizing and fitting controls."""

    type: Literal["Image"] = Field(default="Image", frozen=True)  # pyright: ignore
    src: str
    """Image URL source."""
    alt: str | None = None
    """Alternate text for accessibility."""
    fit: Literal["cover", "contain", "fill", "scale-down", "none"] | None = None
    """How the image should fit within the container."""
    position: (
        Literal[
            "top left",
            "top",
            "top right",
            "left",
            "center",
            "right",
            "bottom left",
            "bottom",
            "bottom right",
        ]
        | None
    ) = None
    """Focal position of the image within the container."""
    radius: RadiusValue | None = None
    """Border radius; accepts a radius token."""
    frame: bool | None = None
    """Draw a subtle frame around the image."""
    flush: bool | None = None
    """Flush the image to the container edge, removing surrounding padding."""
    height: int | str | None = None
    """Explicit height; px or CSS string."""
    width: int | str | None = None
    """Explicit width; px or CSS string."""
    size: int | str | None = None
    """Shorthand to set both width and height; px or CSS string."""
    minHeight: int | str | None = None
    """Minimum height; px or CSS string."""
    minWidth: int | str | None = None
    """Minimum width; px or CSS string."""
    minSize: int | str | None = None
    """Shorthand to set both minWidth and minHeight; px or CSS string."""
    maxHeight: int | str | None = None
    """Maximum height; px or CSS string."""
    maxWidth: int | str | None = None
    """Maximum width; px or CSS string."""
    maxSize: int | str | None = None
    """Shorthand to set both maxWidth and maxHeight; px or CSS string."""
    margin: int | str | Spacing | None = None
    """Outer margin; spacing unit, CSS string, or margin object."""
    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`
    """
    aspectRatio: float | str | None = None
    """Aspect ratio of the box (e.g., 16/9); number or CSS string."""
    flex: int | str | None = None
    """Flex growth/shrink factor."""

src instance-attribute

src: str

Image URL source.

alt class-attribute instance-attribute

alt: str | None = None

Alternate text for accessibility.

fit class-attribute instance-attribute

fit: (
    Literal[
        "cover", "contain", "fill", "scale-down", "none"
    ]
    | None
) = None

How the image should fit within the container.

position class-attribute instance-attribute

position: (
    Literal[
        "top left",
        "top",
        "top right",
        "left",
        "center",
        "right",
        "bottom left",
        "bottom",
        "bottom right",
    ]
    | None
) = None

Focal position of the image within the container.

radius class-attribute instance-attribute

radius: RadiusValue | None = None

Border radius; accepts a radius token.

frame class-attribute instance-attribute

frame: bool | None = None

Draw a subtle frame around the image.

flush class-attribute instance-attribute

flush: bool | None = None

Flush the image to the container edge, removing surrounding padding.

height class-attribute instance-attribute

height: int | str | None = None

Explicit height; px or CSS string.

width class-attribute instance-attribute

width: int | str | None = None

Explicit width; px or CSS string.

size class-attribute instance-attribute

size: int | str | None = None

Shorthand to set both width and height; px or CSS string.

minHeight class-attribute instance-attribute

minHeight: int | str | None = None

Minimum height; px or CSS string.

minWidth class-attribute instance-attribute

minWidth: int | str | None = None

Minimum width; px or CSS string.

minSize class-attribute instance-attribute

minSize: int | str | None = None

Shorthand to set both minWidth and minHeight; px or CSS string.

maxHeight class-attribute instance-attribute

maxHeight: int | str | None = None

Maximum height; px or CSS string.

maxWidth class-attribute instance-attribute

maxWidth: int | str | None = None

Maximum width; px or CSS string.

maxSize class-attribute instance-attribute

maxSize: int | str | None = None

Shorthand to set both maxWidth and maxHeight; px or CSS string.

margin class-attribute instance-attribute

margin: int | str | Spacing | None = None

Outer margin; spacing unit, CSS string, or margin object.

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

aspectRatio class-attribute instance-attribute

aspectRatio: float | str | None = None

Aspect ratio of the box (e.g., 16/9); number or CSS string.

flex class-attribute instance-attribute

flex: int | str | None = None

Flex growth/shrink factor.

Button

Bases: WidgetComponentBase

Button component optionally wired to an action.

Source code in chatkit/widgets.py

class Button(WidgetComponentBase):
    """Button component optionally wired to an action."""

    type: Literal["Button"] = Field(default="Button", frozen=True)  # pyright: ignore
    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: ActionConfig | None = None
    """Action dispatched on click."""
    iconStart: WidgetIcon | None = None
    """Icon shown before the label; can be used for icon-only buttons."""
    iconEnd: WidgetIcon | 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: WidgetIcon | None = None

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

iconEnd class-attribute instance-attribute

iconEnd: WidgetIcon | 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.

Spacer

Bases: WidgetComponentBase

Flexible spacer used to push content apart.

Source code in chatkit/widgets.py

class Spacer(WidgetComponentBase):
    """Flexible spacer used to push content apart."""

    type: Literal["Spacer"] = Field(default="Spacer", frozen=True)  # pyright: ignore
    minSize: int | str | None = None
    """Minimum size the spacer should occupy along the flex direction."""

minSize class-attribute instance-attribute

minSize: int | str | None = None

Minimum size the spacer should occupy along the flex direction.

SelectOption

Bases: TypedDict

Selectable option used by the Select widget.

Source code in chatkit/widgets.py

class SelectOption(TypedDict):
    """Selectable option used by the ``Select`` widget."""

    value: str
    """Option value submitted with the form."""
    label: str
    """Human-readable label for the option."""
    disabled: NotRequired[bool]
    """Disable the option."""
    description: NotRequired[str]
    """Displayed as secondary text below the option `label`."""

value instance-attribute

value: str

Option value submitted with the form.

label instance-attribute

label: str

Human-readable label for the option.

disabled instance-attribute

disabled: NotRequired[bool]

Disable the option.

description instance-attribute

description: NotRequired[str]

Displayed as secondary text below the option label.

Select

Bases: WidgetComponentBase

Select dropdown component.

Source code in chatkit/widgets.py

class Select(WidgetComponentBase):
    """Select dropdown component."""

    type: Literal["Select"] = Field(default="Select", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    options: list[SelectOption]
    """List of selectable options."""
    onChangeAction: ActionConfig | None = None
    """Action dispatched when the value changes."""
    placeholder: str | None = None
    """Placeholder text shown when no value is selected."""
    defaultValue: str | None = None
    """Initial value of the select."""
    variant: ControlVariant | None = None
    """Visual style of the select; accepts a control variant token."""
    size: ControlSize | None = None
    """Controls the size of the select control."""
    pill: bool | None = None
    """Determines if the select should be fully rounded (pill)."""
    block: bool | None = None
    """Extend the select to 100% of the available width."""
    clearable: bool | None = None
    """Show a clear control to unset the value."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

options instance-attribute

options: list[SelectOption]

List of selectable options.

onChangeAction class-attribute instance-attribute

onChangeAction: ActionConfig | None = None

Action dispatched when the value changes.

placeholder class-attribute instance-attribute

placeholder: str | None = None

Placeholder text shown when no value is selected.

defaultValue class-attribute instance-attribute

defaultValue: str | None = None

Initial value of the select.

variant class-attribute instance-attribute

variant: ControlVariant | None = None

Visual style of the select; accepts a control variant token.

size class-attribute instance-attribute

size: ControlSize | None = None

Controls the size of the select control.

pill class-attribute instance-attribute

pill: bool | None = None

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

block class-attribute instance-attribute

block: bool | None = None

Extend the select to 100% of the available width.

clearable class-attribute instance-attribute

clearable: bool | None = None

Show a clear control to unset the value.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.

DatePicker

Bases: WidgetComponentBase

Date picker input component.

Source code in chatkit/widgets.py

class DatePicker(WidgetComponentBase):
    """Date picker input component."""

    type: Literal["DatePicker"] = Field(default="DatePicker", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    onChangeAction: ActionConfig | None = None
    """Action dispatched when the date value changes."""
    placeholder: str | None = None
    """Placeholder text shown when no date is selected."""
    defaultValue: datetime | None = None
    """Initial value of the date picker."""
    min: datetime | None = None
    """Earliest selectable date (inclusive)."""
    max: datetime | None = None
    """Latest selectable date (inclusive)."""
    variant: ControlVariant | None = None
    """Visual variant of the datepicker control."""
    size: ControlSize | None = None
    """Controls the size of the datepicker control."""
    side: Literal["top", "bottom", "left", "right"] | None = None
    """Preferred side to render the calendar."""
    align: Literal["start", "center", "end"] | None = None
    """Preferred alignment of the calendar relative to the control."""
    pill: bool | None = None
    """Determines if the datepicker should be fully rounded (pill)."""
    block: bool | None = None
    """Extend the datepicker to 100% of the available width."""
    clearable: bool | None = None
    """Show a clear control to unset the value."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

onChangeAction class-attribute instance-attribute

onChangeAction: ActionConfig | None = None

Action dispatched when the date value changes.

placeholder class-attribute instance-attribute

placeholder: str | None = None

Placeholder text shown when no date is selected.

defaultValue class-attribute instance-attribute

defaultValue: datetime | None = None

Initial value of the date picker.

min class-attribute instance-attribute

min: datetime | None = None

Earliest selectable date (inclusive).

max class-attribute instance-attribute

max: datetime | None = None

Latest selectable date (inclusive).

variant class-attribute instance-attribute

variant: ControlVariant | None = None

Visual variant of the datepicker control.

size class-attribute instance-attribute

size: ControlSize | None = None

Controls the size of the datepicker control.

side class-attribute instance-attribute

side: Literal["top", "bottom", "left", "right"] | None = (
    None
)

Preferred side to render the calendar.

align class-attribute instance-attribute

align: Literal['start', 'center', 'end'] | None = None

Preferred alignment of the calendar relative to the control.

pill class-attribute instance-attribute

pill: bool | None = None

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

block class-attribute instance-attribute

block: bool | None = None

Extend the datepicker to 100% of the available width.

clearable class-attribute instance-attribute

clearable: bool | None = None

Show a clear control to unset the value.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.

Checkbox

Bases: WidgetComponentBase

Checkbox input component.

Source code in chatkit/widgets.py

class Checkbox(WidgetComponentBase):
    """Checkbox input component."""

    type: Literal["Checkbox"] = Field(default="Checkbox", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    label: str | None = None
    """Optional label text rendered next to the checkbox."""
    defaultChecked: str | None = None
    """The initial checked state of the checkbox."""
    onChangeAction: ActionConfig | None = None
    """Action dispatched when the checked state changes."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""
    required: bool | None = None
    """Mark the checkbox as required for form submission."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

label class-attribute instance-attribute

label: str | None = None

Optional label text rendered next to the checkbox.

defaultChecked class-attribute instance-attribute

defaultChecked: str | None = None

The initial checked state of the checkbox.

onChangeAction class-attribute instance-attribute

onChangeAction: ActionConfig | None = None

Action dispatched when the checked state changes.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.

required class-attribute instance-attribute

required: bool | None = None

Mark the checkbox as required for form submission.

Input

Bases: WidgetComponentBase

Single-line text input component.

Source code in chatkit/widgets.py

class Input(WidgetComponentBase):
    """Single-line text input component."""

    type: Literal["Input"] = Field(default="Input", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    inputType: Literal["number", "email", "text", "password", "tel", "url"] | None = (
        None
    )
    """Native input type."""
    defaultValue: str | None = None
    """Initial value of the input."""
    required: bool | None = None
    """Mark the input as required for form submission."""
    pattern: str | None = None
    """Regex pattern for input validation."""
    placeholder: str | None = None
    """Placeholder text shown when empty."""
    allowAutofillExtensions: bool | None = None
    """Allow password managers / autofill extensions to appear."""
    autoSelect: bool | None = None
    """Select all contents of the input when it mounts."""
    autoFocus: bool | None = None
    """Autofocus the input when it mounts."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""
    variant: Literal["soft", "outline"] | None = None
    """Visual style of the input."""
    size: ControlSize | None = None
    """Controls the size of the input control."""
    gutterSize: Literal["2xs", "xs", "sm", "md", "lg", "xl"] | None = None
    """Controls gutter on the edges of the input; overrides value from `size`."""
    pill: bool | None = None
    """Determines if the input should be fully rounded (pill)."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

inputType class-attribute instance-attribute

inputType: (
    Literal[
        "number", "email", "text", "password", "tel", "url"
    ]
    | None
) = None

Native input type.

defaultValue class-attribute instance-attribute

defaultValue: str | None = None

Initial value of the input.

required class-attribute instance-attribute

required: bool | None = None

Mark the input as required for form submission.

pattern class-attribute instance-attribute

pattern: str | None = None

Regex pattern for input validation.

placeholder class-attribute instance-attribute

placeholder: str | None = None

Placeholder text shown when empty.

allowAutofillExtensions class-attribute instance-attribute

allowAutofillExtensions: bool | None = None

Allow password managers / autofill extensions to appear.

autoSelect class-attribute instance-attribute

autoSelect: bool | None = None

Select all contents of the input when it mounts.

autoFocus class-attribute instance-attribute

autoFocus: bool | None = None

Autofocus the input when it mounts.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.

variant class-attribute instance-attribute

variant: Literal['soft', 'outline'] | None = None

Visual style of the input.

size class-attribute instance-attribute

size: ControlSize | None = None

Controls the size of the input control.

gutterSize class-attribute instance-attribute

gutterSize: (
    Literal["2xs", "xs", "sm", "md", "lg", "xl"] | None
) = None

Controls gutter on the edges of the input; overrides value from size.

pill class-attribute instance-attribute

pill: bool | None = None

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

Label

Bases: WidgetComponentBase

Form label associated with a field.

Source code in chatkit/widgets.py

class Label(WidgetComponentBase):
    """Form label associated with a field."""

    type: Literal["Label"] = Field(default="Label", frozen=True)  # pyright: ignore
    value: str
    """Text content of the label."""
    fieldName: str
    """Name of the field this label describes."""
    size: TextSize | None = None
    """Size of the label text; accepts a text size token."""
    weight: Literal["normal", "medium", "semibold", "bold"] | None = None
    """Font weight; accepts a font weight token."""
    textAlign: TextAlign | None = None
    """Horizontal text alignment."""
    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`
    """

value instance-attribute

value: str

Text content of the label.

fieldName instance-attribute

fieldName: str

Name of the field this label describes.

size class-attribute instance-attribute

size: TextSize | None = None

Size of the label text; accepts a text size token.

weight class-attribute instance-attribute

weight: (
    Literal["normal", "medium", "semibold", "bold"] | None
) = None

Font weight; accepts a font weight token.

textAlign class-attribute instance-attribute

textAlign: TextAlign | None = None

Horizontal text alignment.

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

RadioOption

Bases: TypedDict

Option inside a RadioGroup widget.

Source code in chatkit/widgets.py

class RadioOption(TypedDict):
    """Option inside a ``RadioGroup`` widget."""

    label: str
    """Label displayed next to the radio option."""
    value: str
    """Value submitted when the radio option is selected."""
    disabled: NotRequired[bool]
    """Disables a specific radio option."""

label instance-attribute

label: str

Label displayed next to the radio option.

value instance-attribute

value: str

Value submitted when the radio option is selected.

disabled instance-attribute

disabled: NotRequired[bool]

Disables a specific radio option.

RadioGroup

Bases: WidgetComponentBase

Grouped radio input control.

Source code in chatkit/widgets.py

class RadioGroup(WidgetComponentBase):
    """Grouped radio input control."""

    type: Literal["RadioGroup"] = Field(default="RadioGroup", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    options: list[RadioOption] | None = None
    """Array of options to render as radio items."""
    ariaLabel: str | None = None
    """Accessible label for the radio group; falls back to `name`."""
    onChangeAction: ActionConfig | None = None
    """Action dispatched when the selected value changes."""
    defaultValue: str | None = None
    """Initial selected value of the radio group."""
    direction: Literal["row", "col"] | None = None
    """Layout direction of the radio items."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles for the entire group."""
    required: bool | None = None
    """Mark the group as required for form submission."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

options class-attribute instance-attribute

options: list[RadioOption] | None = None

Array of options to render as radio items.

ariaLabel class-attribute instance-attribute

ariaLabel: str | None = None

Accessible label for the radio group; falls back to name.

onChangeAction class-attribute instance-attribute

onChangeAction: ActionConfig | None = None

Action dispatched when the selected value changes.

defaultValue class-attribute instance-attribute

defaultValue: str | None = None

Initial selected value of the radio group.

direction class-attribute instance-attribute

direction: Literal['row', 'col'] | None = None

Layout direction of the radio items.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles for the entire group.

required class-attribute instance-attribute

required: bool | None = None

Mark the group as required for form submission.

Textarea

Bases: WidgetComponentBase

Multiline text input component.

Source code in chatkit/widgets.py

class Textarea(WidgetComponentBase):
    """Multiline text input component."""

    type: Literal["Textarea"] = Field(default="Textarea", frozen=True)  # pyright: ignore
    name: str
    """The name of the form control field used when submitting forms."""
    defaultValue: str | None = None
    """Initial value of the textarea."""
    required: bool | None = None
    """Mark the textarea as required for form submission."""
    pattern: str | None = None
    """Regex pattern for input validation."""
    placeholder: str | None = None
    """Placeholder text shown when empty."""
    autoSelect: bool | None = None
    """Select all contents of the textarea when it mounts."""
    autoFocus: bool | None = None
    """Autofocus the textarea when it mounts."""
    disabled: bool | None = None
    """Disable interactions and apply disabled styles."""
    variant: Literal["soft", "outline"] | None = None
    """Visual style of the textarea."""
    size: ControlSize | None = None
    """Controls the size of the textarea control."""
    gutterSize: Literal["2xs", "xs", "sm", "md", "lg", "xl"] | None = None
    """Controls gutter on the edges of the textarea; overrides value from `size`."""
    rows: int | None = None
    """Initial number of visible rows."""
    autoResize: bool | None = None
    """Automatically grow/shrink to fit content."""
    maxRows: int | None = None
    """Maximum number of rows when auto-resizing."""
    allowAutofillExtensions: bool | None = None
    """Allow password managers / autofill extensions to appear."""

name instance-attribute

name: str

The name of the form control field used when submitting forms.

defaultValue class-attribute instance-attribute

defaultValue: str | None = None

Initial value of the textarea.

required class-attribute instance-attribute

required: bool | None = None

Mark the textarea as required for form submission.

pattern class-attribute instance-attribute

pattern: str | None = None

Regex pattern for input validation.

placeholder class-attribute instance-attribute

placeholder: str | None = None

Placeholder text shown when empty.

autoSelect class-attribute instance-attribute

autoSelect: bool | None = None

Select all contents of the textarea when it mounts.

autoFocus class-attribute instance-attribute

autoFocus: bool | None = None

Autofocus the textarea when it mounts.

disabled class-attribute instance-attribute

disabled: bool | None = None

Disable interactions and apply disabled styles.

variant class-attribute instance-attribute

variant: Literal['soft', 'outline'] | None = None

Visual style of the textarea.

size class-attribute instance-attribute

size: ControlSize | None = None

Controls the size of the textarea control.

gutterSize class-attribute instance-attribute

gutterSize: (
    Literal["2xs", "xs", "sm", "md", "lg", "xl"] | None
) = None

Controls gutter on the edges of the textarea; overrides value from size.

rows class-attribute instance-attribute

rows: int | None = None

Initial number of visible rows.

autoResize class-attribute instance-attribute

autoResize: bool | None = None

Automatically grow/shrink to fit content.

maxRows class-attribute instance-attribute

maxRows: int | None = None

Maximum number of rows when auto-resizing.

allowAutofillExtensions class-attribute instance-attribute

allowAutofillExtensions: bool | None = None

Allow password managers / autofill extensions to appear.

Transition

Bases: WidgetComponentBase

Wrapper enabling transitions for a child component.

Source code in chatkit/widgets.py

class Transition(WidgetComponentBase):
    """Wrapper enabling transitions for a child component."""

    type: Literal["Transition"] = Field(default="Transition", frozen=True)  # pyright: ignore
    children: WidgetComponent | None
    """The child component to animate layout changes for."""

children instance-attribute

children: WidgetComponent | None

The child component to animate layout changes for.

Chart

Bases: WidgetComponentBase

Data visualization component for simple bar/line/area charts.

Source code in chatkit/widgets.py

class Chart(WidgetComponentBase):
    """Data visualization component for simple bar/line/area charts."""

    type: Literal["Chart"] = Field(default="Chart", frozen=True)  # pyright: ignore
    data: list[dict[str, str | int | float]]
    """Tabular data for the chart, where each row maps field names to values."""
    series: list[Series]
    """One or more series definitions that describe how to visualize data fields."""
    xAxis: str | XAxisConfig
    """X-axis configuration; either a `dataKey` string or a config object."""
    showYAxis: bool | None = None
    """Controls whether the Y axis is rendered."""
    showLegend: bool | None = None
    """Controls whether a legend is rendered."""
    showTooltip: bool | None = None
    """Controls whether a tooltip is rendered when hovering over a datapoint."""
    barGap: int | None = None
    """Gap between bars within the same category (in px)."""
    barCategoryGap: int | None = None
    """Gap between bar categories/groups (in px)."""
    flex: int | str | None = None
    """Flex growth/shrink factor for layout."""
    height: int | str | None = None
    """Explicit height; px or CSS string."""
    width: int | str | None = None
    """Explicit width; px or CSS string."""
    size: int | str | None = None
    """Shorthand to set both width and height; px or CSS string."""
    minHeight: int | str | None = None
    """Minimum height; px or CSS string."""
    minWidth: int | str | None = None
    """Minimum width; px or CSS string."""
    minSize: int | str | None = None
    """Shorthand to set both minWidth and minHeight; px or CSS string."""
    maxHeight: int | str | None = None
    """Maximum height; px or CSS string."""
    maxWidth: int | str | None = None
    """Maximum width; px or CSS string."""
    maxSize: int | str | None = None
    """Shorthand to set both maxWidth and maxHeight; px or CSS string."""
    aspectRatio: float | str | None = None
    """Aspect ratio of the chart area (e.g., 16/9); number or CSS string."""

data instance-attribute

data: list[dict[str, str | int | float]]

Tabular data for the chart, where each row maps field names to values.

series instance-attribute

series: list[Series]

One or more series definitions that describe how to visualize data fields.

xAxis instance-attribute

xAxis: str | XAxisConfig

X-axis configuration; either a dataKey string or a config object.

showYAxis class-attribute instance-attribute

showYAxis: bool | None = None

Controls whether the Y axis is rendered.

showLegend class-attribute instance-attribute

showLegend: bool | None = None

Controls whether a legend is rendered.

showTooltip class-attribute instance-attribute

showTooltip: bool | None = None

Controls whether a tooltip is rendered when hovering over a datapoint.

barGap class-attribute instance-attribute

barGap: int | None = None

Gap between bars within the same category (in px).

barCategoryGap class-attribute instance-attribute

barCategoryGap: int | None = None

Gap between bar categories/groups (in px).

flex class-attribute instance-attribute

flex: int | str | None = None

Flex growth/shrink factor for layout.

height class-attribute instance-attribute

height: int | str | None = None

Explicit height; px or CSS string.

width class-attribute instance-attribute

width: int | str | None = None

Explicit width; px or CSS string.

size class-attribute instance-attribute

size: int | str | None = None

Shorthand to set both width and height; px or CSS string.

minHeight class-attribute instance-attribute

minHeight: int | str | None = None

Minimum height; px or CSS string.

minWidth class-attribute instance-attribute

minWidth: int | str | None = None

Minimum width; px or CSS string.

minSize class-attribute instance-attribute

minSize: int | str | None = None

Shorthand to set both minWidth and minHeight; px or CSS string.

maxHeight class-attribute instance-attribute

maxHeight: int | str | None = None

Maximum height; px or CSS string.

maxWidth class-attribute instance-attribute

maxWidth: int | str | None = None

Maximum width; px or CSS string.

maxSize class-attribute instance-attribute

maxSize: int | str | None = None

Shorthand to set both maxWidth and maxHeight; px or CSS string.

aspectRatio class-attribute instance-attribute

aspectRatio: float | str | None = None

Aspect ratio of the chart area (e.g., 16/9); number or CSS string.

XAxisConfig

Bases: TypedDict

Configuration object for the X axis.

Source code in chatkit/widgets.py

class XAxisConfig(TypedDict):
    """Configuration object for the X axis."""

    dataKey: str
    """Field name from each data row to use for X-axis categories."""
    hide: NotRequired[bool]
    """Hide the X axis line, ticks, and labels when true."""
    labels: NotRequired[dict[str, str]]
    """Custom mapping of tick values to display labels."""

dataKey instance-attribute

dataKey: str

Field name from each data row to use for X-axis categories.

hide instance-attribute

hide: NotRequired[bool]

Hide the X axis line, ticks, and labels when true.

labels instance-attribute

labels: NotRequired[dict[str, str]]

Custom mapping of tick values to display labels.

BarSeries

Bases: BaseModel

A bar series plotted from a numeric dataKey. Supports stacking.

Source code in chatkit/widgets.py

class BarSeries(BaseModel):
    """A bar series plotted from a numeric `dataKey`. Supports stacking."""

    type: Literal["bar"] = Field(default="bar", frozen=True)
    label: str | None
    """Legend label for the series."""
    dataKey: str
    """Field name from each data row that contains the numeric value."""
    stack: str | None = None
    """Optional stack group ID. Series with the same ID stack together."""
    color: str | ThemeColor | None = None
    """
    Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

    Chart color tokens: `blue` `purple` `orange` `green` `red` `yellow` `pink`

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

    Note: By default, a color will be sequentially assigned from the chart series colors.
    """

label instance-attribute

label: str | None

Legend label for the series.

dataKey instance-attribute

dataKey: str

Field name from each data row that contains the numeric value.

stack class-attribute instance-attribute

stack: str | None = None

Optional stack group ID. Series with the same ID stack together.

color class-attribute instance-attribute

color: str | ThemeColor | None = None

Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

Chart color tokens: blue purple orange green red yellow pink

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

Note: By default, a color will be sequentially assigned from the chart series colors.

AreaSeries

Bases: BaseModel

An area series plotted from a numeric dataKey. Supports stacking and curves.

Source code in chatkit/widgets.py

class AreaSeries(BaseModel):
    """An area series plotted from a numeric `dataKey`. Supports stacking and curves."""

    type: Literal["area"] = Field(default="area", frozen=True)
    label: str | None
    """Legend label for the series."""
    dataKey: str
    """Field name from each data row that contains the numeric value."""
    stack: str | None = None
    """Optional stack group ID. Series with the same ID stack together."""
    color: str | ThemeColor | None = None
    """
    Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

    Chart color tokens: `blue` `purple` `orange` `green` `red` `yellow` `pink`

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

    Note: By default, a color will be sequentially assigned from the chart series colors.
    """
    curveType: None | Literal[CurveType] = None
    """Interpolation curve type used to connect points."""

label instance-attribute

label: str | None

Legend label for the series.

dataKey instance-attribute

dataKey: str

Field name from each data row that contains the numeric value.

stack class-attribute instance-attribute

stack: str | None = None

Optional stack group ID. Series with the same ID stack together.

color class-attribute instance-attribute

color: str | ThemeColor | None = None

Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

Chart color tokens: blue purple orange green red yellow pink

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

Note: By default, a color will be sequentially assigned from the chart series colors.

curveType class-attribute instance-attribute

curveType: None | Literal[CurveType] = None

Interpolation curve type used to connect points.

LineSeries

Bases: BaseModel

A line series plotted from a numeric dataKey. Supports curves.

Source code in chatkit/widgets.py

class LineSeries(BaseModel):
    """A line series plotted from a numeric `dataKey`. Supports curves."""

    type: Literal["line"] = Field(default="line", frozen=True)
    label: str | None
    """Legend label for the series."""
    dataKey: str
    """Field name from each data row that contains the numeric value."""
    color: str | ThemeColor | None = None
    """
    Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

    Chart color tokens: `blue` `purple` `orange` `green` `red` `yellow` `pink`

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

    Note: By default, a color will be sequentially assigned from the chart series colors.
    """
    curveType: None | Literal[CurveType] = None
    """Interpolation curve type used to connect points."""

label instance-attribute

label: str | None

Legend label for the series.

dataKey instance-attribute

dataKey: str

Field name from each data row that contains the numeric value.

color class-attribute instance-attribute

color: str | ThemeColor | None = None

Color for the series; accepts chart color token, a primitive color token, a CSS string, or theme-aware { light, dark }.

Chart color tokens: blue purple orange green red yellow pink

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

Note: By default, a color will be sequentially assigned from the chart series colors.

curveType class-attribute instance-attribute

curveType: None | Literal[CurveType] = None

Interpolation curve type used to connect points.