ki-suggestions
@kimen/elements/ki-suggestions- Source
- Agent reference
Use cards to offer conversation starters with a short description. Use chips for follow-up prompts after an answer.
<ki-suggestions id="starters" label="Start a conversation" variant="cards" mode="fill"><ki-suggestion description="From the on-call reports">Summarise the incidents</ki-suggestion><ki-suggestion description="For the merged pull requests">Draft release notes</ki-suggestion></ki-suggestions><ki-suggestions label="Follow-up suggestions"><ki-suggestion>Which ones recur?</ki-suggestion><ki-suggestion>Group them by service</ki-suggestion><ki-suggestion>Turn this into a table</ki-suggestion></ki-suggestions>Supply a group label and place each ki-suggestion directly inside it.
Write the prompt as plain text. That title is also the button’s accessible
name. A supplied description gives assistive technology separate context.
Tab moves through the buttons in reading order. Enter or Space chooses the
focused suggestion.
Connect a composer
The group dispatches a bubbling, composed and cancelable ki-select. Read
event.detail.text to get the chosen prompt. In the default send mode, the
application’s event handler sends the prompt. Set mode="fill" to populate
the composer’s draft for editing.
Assign composer in JavaScript. It accepts a writable string value and a
focus() method. Both modes focus the composer after dispatch. Fill mode
also replaces its draft. Cancel the event with preventDefault() when your
handler takes over value or focus.
Add a draft field after the starter group in the first example.
<label for="draft">Message</label><textarea id="draft"></textarea>const suggestions = document.querySelector('#starters');suggestions.composer = document.querySelector('#draft');Register both tags when using direct imports or framework wrappers.
API reference
When to use: offer suggested prompts to start or continue an assistant conversation.
When not to use: choose a form value, switch views, or display static example text.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | – | Required accessible name for the group. |
mode | mode | "fill" | "send" | 'send' | Send through the application or fill its attached editor for revision. |
variant | variant | "cards" | "chips" | 'chips' | Wrapping chips for follow-ups or cards with room for a description. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-select | CustomEvent<{ text: string }> | Reports the chosen prompt title. Use this event to send the prompt in send mode. Cancel it to take over the default composer write and focus. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-suggestion children in reading order. |
CSS parts
| Part | Description |
|---|---|
group | The container that lays out the suggested prompts. |
CSS custom properties
The public styling contract of ki-suggestions: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-suggestion-card-backdrop-filter | Filter behind the card surface. |
--ki-suggestion-card-bg | Resting card surface. |
--ki-suggestion-card-bg-image | Image layered over the card surface. |
--ki-suggestion-card-border | Resting card boundary. |
--ki-suggestion-card-fg | Resting card title. |
--ki-suggestion-card-hover-bg | Card surface on a hovering device. |
--ki-suggestion-card-hover-fg | Title over the card hover surface. |
--ki-suggestion-card-inset | Block padding of each starter card. |
--ki-suggestion-card-pressed-bg | Card surface while a pointer or key holds activation. |
--ki-suggestion-card-pressed-fg | Title over the pressed card surface. |
--ki-suggestion-card-radius | Corners of a starter card. |
--ki-suggestion-card-weight | Weight of the card title. |
--ki-suggestions-card-width | Maximum inline size of each starter card. |
--ki-suggestions-font-family | Typeface inherited by the suggestion group. |
--ki-suggestions-gap | Spacing between suggestions. |