Choice

kai-choice

A “pick one of N” card — set the options in JavaScript, the user chooses one, and your app receives a typed kai-card action event.

• Shadow DOM
• Card-contract events
• Rich option rows
• Optional free-text escape (allowOther)
• Resolves to read-only after submit

Preview

When to use

Use <kai-choice> when the model needs the user to pick exactly one option before proceeding — plan selection, tone preference, next-step branching. Drop it standalone or let <kai-cards> dispatch it from a stream. Use <kai-confirm> for yes/no, <kai-form> for multi-field input.

Usage

Set data in JavaScript (it’s an object) and listen for the kai-card CustomEvent:

<kai-choice id="ch" heading="Choose a plan"></kai-choice>

<script type="module">
  import '@kitn.ai/ui/elements';
  const el = document.getElementById('ch');

  el.data = {
    prompt: 'Which plan fits your team?',
    options: [
      { id: 'free',  label: 'Free',     meta: '$0' },
      { id: 'pro',   label: 'Pro',      meta: '$12/seat', recommended: true },
      { id: 'biz',   label: 'Business', meta: '$29/seat' },
    ],
  };

  el.addEventListener('kai-card', (e) => {
    const ev = e.detail; // CardEvent
    if (ev.kind === 'action') console.log('chose:', ev.action, ev.payload);
  });
</script>

• data — required fields per option: id and label. Optional: description, meta, recommended, media + imageAlt, disabled, payload.
• allowOther appends an “Other…” row revealing an inline text input; submits as action: '__other__' with payload: { text }.
• After submit the card renders read-only. Restore a resolved state on reload via el.resolution = { kind: 'action', action: 'option-id' }.

Examples

Plans with Pricing

Code

Rows with Images

Code

Quick Replies with Free-Text Escape

allowOther appends an “Other…” row that reveals an inline text field when selected.

Code

Resolved (Read-only)

Pre-render the post-submit view — useful for restoring persisted choices on reload.

Code

Error State

A malformed definition (empty options) triggers the inline error view and emits { kind: 'error' }.

Code

Props

Property	Type	Default	Notes
data	Record<string, unknown>	—	The choice definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { prompt, options:[…], allowOther?, submitLabel? }`. Import `ChoiceCardData` from `@kitn.ai/ui` for the full shape.
cardId	string	—	Stable card id correlating every emitted CardEvent. Attribute: `card-id`.
heading	string	—	Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`.
resolution	Record<string, unknown>	—	Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`.

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

ChoiceCard

---

Need a hand? Report a bug Ask for help