@loke/ui/skills/command/references/command-components.md

# Command component reference

Import path: `@loke/ui/command`

## Sub-component exports

### `Command`

Root container. Manages filtering state, keyboard navigation, and item registration.

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | — | Accessible label for the command menu (screen readers only) |
| `shouldFilter` | `boolean` | `true` | Set to `false` to disable built-in filtering (e.g. server-side search) |
| `filter` | `(value, search, keywords?) => number` | `commandScore` | Custom scoring function. Return `0` to hide, higher = better match |
| `value` | `string` | — | Controlled selected item value |
| `defaultValue` | `string` | — | Initial selected item value (uncontrolled) |
| `onValueChange` | `(value: string) => void` | — | Called when selected item changes |
| `loop` | `boolean` | `false` | Wrap keyboard navigation around ends of list |
| `disablePointerSelection` | `boolean` | `false` | Disable selection via mouse pointer |
| `vimBindings` | `boolean` | `true` | Enable ctrl+n/j/p/k navigation shortcuts |

---

### `CommandInput`

Search input. Wired to filtering state — typing updates the search query and re-scores items.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | — | Controlled input value |
| `onValueChange` | `(search: string) => void` | — | Called on each keystroke with new search string |
| `placeholder` | `string` | — | Input placeholder text |

Does not accept `type` or `onChange` — these are managed internally.

---

### `CommandList`

Scrollable list container. Provides `role="listbox"`, accessible `aria-label`, and sets `--loke-cmd-list-height` CSS variable (useful for animated resizing).

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | — | Accessible label for the listbox |

**Required wrapper** — items must be descendants of `CommandList` for correct ARIA semantics.

---

### `CommandItem`

A selectable item. Registered with the command store; hidden when its score is `0`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | inferred from `textContent` | Item value used for filtering and `onSelect` callback. Set explicitly when children are not plain text |
| `onSelect` | `(value: string) => void` | — | Called on click or Enter/Space keypress |
| `disabled` | `boolean` | `false` | Prevents selection; item is hidden from keyboard navigation |
| `keywords` | `string[]` | — | Extra terms to match during filtering (not shown in UI) |
| `forceMount` | `boolean` | `false` | Always render regardless of filter score |

Sets `data-selected` when keyboard-focused, `aria-disabled` when disabled.

---

### `CommandGroup`

Groups related items. Hidden automatically when none of its items match the current search (unless `forceMount` is set).

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | — | Unique identifier; required when no `heading` is provided |
| `heading` | `ReactNode` | — | Visual heading rendered above the group's items |
| `forceMount` | `boolean` | `false` | Always render even when all items are filtered out |

---

### `CommandGroupHeading`

Renders the heading label inside a `CommandGroup`. Accepts standard `div` props.

Use instead of the `heading` prop on `CommandGroup` when you need to style or compose the heading element directly.

---

### `CommandEmpty`

Shown when the filtered item count is `0`. Hidden otherwise.

Accepts standard `div` props and `children`.

---

### `CommandLoading`

Loading state indicator. Renders a `progressbar` role element.

| Prop | Type | Default | Description |
|---|---|---|---|
| `progress` | `number` | — | Value 0–100 for `aria-valuenow` |
| `label` | `string` | — | Accessible label for the progress bar (screen readers only) |

Shown regardless of filtering state — use conditionally in your render logic.

---

### `CommandSeparator`

A visual divider between groups. Hidden when there is an active search query.

| Prop | Type | Default | Description |
|---|---|---|---|
| `alwaysRender` | `boolean` | `false` | Keep separator visible even during active search |

---

### `createCommandScope`

Scope factory for embedding `Command` inside compound components that need nested context isolation. See `context-and-collection` skill for scope usage.

---

## Data attributes

These attributes are set on rendered elements and can be targeted with CSS selectors:

| Attribute | Element | Values |
|---|---|---|
| `data-selected` | `CommandItem` | `""` when keyboard-focused |
| `aria-disabled` | `CommandItem` | `"true"` when disabled |
| `loke-cmd-item` | `CommandItem` | `""` always (selector hook) |
| `loke-cmd-group` | `CommandGroup` wrapper | `""` always |
| `loke-cmd-group-items` | `CommandGroup` items container | `""` always |
| `loke-cmd-group-heading` | `CommandGroupHeading` | `""` always |

## CSS variables

| Variable | Set by | Description |
|---|---|---|
| `--loke-cmd-list-height` | `CommandList` | Current scrollable list height; updates as items filter in/out |

## Internal selectors (informational)

Used by the component internals for DOM queries:

```ts
const ITEM_SELECTOR = `[loke-cmd-item=""]`;
const VALID_ITEM_SELECTOR = `[loke-cmd-item=""]:not([aria-disabled="true"])`;
const GROUP_SELECTOR = `[loke-cmd-group=""]`;
```