Command

kai-command

Filters as the user types while keyboard navigation keeps working, for picking from long lists.

• Shadow DOM
• Grouped + filterable
• Full keyboard nav
• role: listbox

Preview

When to use

When the user has to pick one thing out of many, fast: an @-mention picker, a slash-command menu, a model switcher. For a static action list, a plain Menu is lighter.

Usage

Set items as a JS property: a flat array, never an attribute. Each item needs an id (echoed back in kai-select) and a label; add group to bucket it under a header, plus icon and description. Listen for kai-select for the picked id, and kai-query-change to drive your own async filtering.

<kai-command placeholder="Search files, chats, people…"></kai-command>
<script type="module">
  import '@kitn.ai/ui/web-components';
  const el = document.querySelector('kai-command');
  // Array prop — set in JS, never as an HTML attribute.
  el.items = [
    { id: 'screen9', label: 'screen9.py', icon: 'file-text', description: '/Users/rob/screen9.py', group: 'Files' },
    { id: 'rs', label: 'Record screen', icon: 'message-circle', group: 'Chats' },
  ];
  el.addEventListener('kai-select', (e) => console.log('picked', e.detail.id));
  el.addEventListener('kai-query-change', (e) => console.log('query', e.detail.value));
</script>

Examples

Mention picker

Grouped across Mac apps, Chats, and Files, each row with an icon and a path.

Code

Slash commands

Actions bucketed into Actions and Settings; drop description and each row is one line.

Code

Ungrouped

Omit group on every item for one flat, unsectioned list.

Code

Props

Property	Type	Default	Notes
theme	"light" | "dark" | "auto"	'auto'	Color mode (`auto` follows prefers-color-scheme).
items	KaiCommandItem[]	—	Flat list of items. Set as a JS property, not an HTML attribute.
placeholder	string	—	Placeholder text for the search input.
emptyLabel	string	—	Label shown when no items match the current query.

Events

Event	Detail	Notes
kai-active-change	{ … }	The highlighted item changed. `detail.id` is `undefined` when nothing is active (e.g. the filtered list is empty).
kai-query-change	{ … }	Fired on every keystroke in the search input.
kai-select	{ … }	Fired when the user selects an item (click or Enter).

Methods

Method	Signature	Notes
focus	(options?: FocusOptions): void	Focus the search combobox input inside the shadow root so the palette is type-ready on demand (Shadow-DOM autofocus is unreliable, so hosts call this after opening the palette).
blur	(): void	Blur the focused search input.
clear	(): void	Reset the search query to empty, re-showing all items, and fire `kai-query-change` with `''`. Mirrors the Escape-key behavior.

Composed from

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

CommandList

---

Need a hand? Report a bug Ask for help