Command

A command menu that filters, ranks and selects its items.

Command menu

<script lang="ts">
	import { Command } from '@sveltery/base/command';
	import styles from './index.module.css';
</script>

<Command.Root label="Command menu" class={styles.Root}>
	<Command.Input placeholder="Type a command or search..." class={styles.Input} />
	<Command.List class={styles.List}>
		<Command.Empty class={styles.Empty}>No results found.</Command.Empty>
		<Command.Group heading="Suggestions" class={styles.Group}>
			<Command.Item class={styles.Item}>Calendar</Command.Item>
			<Command.Item class={styles.Item} keywords={['emoji']}>Search Emoji</Command.Item>
			<Command.Item class={styles.Item} disabled>Calculator</Command.Item>
		</Command.Group>
		<Command.Separator class={styles.Separator} />
		<Command.Group heading="Settings" class={styles.Group}>
			<Command.Item class={styles.Item}>Profile</Command.Item>
			<Command.Item class={styles.Item}>Billing</Command.Item>
		</Command.Group>
	</Command.List>
</Command.Root>

Command ports cmdk 1.1.1. It renders cmdk’s elements, cmdk-* attributes, roles and ARIA, so styles written for cmdk select the same markup. Sveltery UI’s Command is built on it.

Anatomy

Import the component and assemble its parts:

Anatomy

<script lang="ts">
	import { Command } from '@sveltery/base/command';
</script>

<Command.Root>
	<Command.Input />
	<Command.List>
		<Command.Empty />
		<Command.Loading />
		<Command.Group>
			<Command.Item />
		</Command.Group>
		<Command.Separator />
		<Command.Item />
	</Command.List>
</Command.Root>

An item’s value is its trimmed text unless you pass value. Typing filters and ranks items with cmdk’s fuzzy scoring. Items that do not match unmount, and the rest render in ranked order. The first matching item is selected, the arrow keys move the selection, and Enter or a click calls the item’s onSelect with its value.

A bound value that names no item is kept, for example while items load, and selects the first item with that value once one mounts. An empty value selects the first item. Use defaultValue to start with an item selected without binding it.

filter(value, search, keywords) returns a score from 0 to 1. A score of 0 hides the item. The default is the exported defaultFilter.

Keyboard

Key	Action
`ArrowDown`, `ArrowUp`	Next or previous item. Wraps around with `loop`.
`Ctrl`+`N` or `J`, `Ctrl`+`P` or `K`	Same as ArrowDown and ArrowUp, unless `vimBindings` is false.
`Meta` with any of the above	Last or first item.
`Alt` with any of the above	First item of the next or previous group.
`Home`, `End`	First or last item.
`Enter`	Calls the selected item’s `onSelect`.

Root ignores a key when a handler called preventDefault() or an input method is composing. Disabled items are never selected by the keyboard or the pointer.

Examples

Server results

For results that you fetch yourself, turn filtering off and render what the server returns. Selection and the keyboard keep working:

Server results

<Command.Root shouldFilter={false}>
	<Command.Input bind:value={query} />
	<Command.List>
		{#if loading}<Command.Loading {progress}>Fetching...</Command.Loading>{/if}
		{#each results as result (result.id)}
			<Command.Item value={result.id}>{result.title}</Command.Item>
		{/each}
		<Command.Empty>Nothing found.</Command.Empty>
	</Command.List>
</Command.Root>

Reading the state

getCommandState() reads the menu’s state from any component inside Root. Its fields are reactive:

Result count

<script lang="ts">
	import { getCommandState } from '@sveltery/base/command';

	const command = getCommandState();
</script>

{#if command.search}<p>{command.count} results</p>{/if}

In a dialog

Put Root inside a Dialog. The menu resets its search and selection each time the popup content mounts again. Bind value on Root and Input to keep them across openings.

Command dialog

<Dialog.Root bind:open>
	<Dialog.Portal>
		<Dialog.Backdrop />
		<Dialog.Popup aria-label="Command menu">
			<Command.Root label="Command menu">
				<Command.Input autofocus placeholder="Type a command..." />
				<Command.List>...</Command.List>
			</Command.Root>
		</Dialog.Popup>
	</Dialog.Portal>
</Dialog.Root>

Where parts render

List and each Group render their parts themselves, in ranked order, and each part leaves only a comment where you write it. So an element you wrap around an Item, Group, Separator, Empty or Loading stays empty: put classes and attributes on the part itself. Other markup written in List or Group renders before its parts. A {#each} or {#if} around parts is fine.

API reference

Root

A command menu that filters, ranks and selects its items. Renders a <div> element.

label string —

Name: label
Description: Accessible label for the command menu, rendered visually hidden.
Type: string

defaultValue string —

Name: defaultValue
Description: The value of the item selected at first. This is the uncontrolled counterpart of value.
Type: string

value string —

Name: value
Description: The selected item's value. Bindable. While it is empty, Root selects the first item. A value that names no item is kept, and selects the first item with that value once one mounts.
To start with a value without binding it, use the defaultValue prop instead.
Type: string
Binding: bind:value

onValueChange function —

Name: onValueChange
Description: Called on every change of the selected value, including the menu's own automatic selection.
Type: (value: string) => void

disablePointerSelection boolean false

Name: disablePointerSelection
Description: Stops pointer movement from selecting items.
Type: boolean
Default: false

filter CommandFilter —

Name: filter
Description: Scores an item against the search from 0 (hidden) to 1 (best). Defaults to defaultFilter.
Type: CommandFilter

onkeydown KeyboardEventHandler<HTMLDivElement> | null —

Name: onkeydown
Description: Runs before the menu's keyboard handling. Call event.preventDefault() to skip it.
Type: KeyboardEventHandler<HTMLDivElement> | null

shouldFilter boolean true

Name: shouldFilter
Description: Set to false to turn off filtering and sorting, for example when the items come from a server search.
Type: boolean
Default: true

vimBindings boolean true

Name: vimBindings
Description: Enables Ctrl+N/J and Ctrl+P/K.
Type: boolean
Default: true

loop boolean false

Name: loop
Description: Wraps the arrow keys around the ends of the list.
Type: boolean
Default: false

Input

The search input of the command menu. Renders an <input> element.

value string —

Name: value
Description: The search text. Bindable.
To start with a search without binding it, use the defaultValue prop instead.
Type: string
Binding: bind:value

List

The list of items, groups and other parts. Renders a <div> element.

label string 'Suggestions'

Name: label
Description: Accessible label for the listbox.
Type: string
Default: 'Suggestions'

Empty

Rendered while no item matches the search. Renders a <div> element.

This part takes no props beyond its element's HTML attributes.

Group

A group of items with an optional heading. Renders a <div> element.

value string —

Name: value
Description: The group's data-value. Defaults to the heading's text.
Type: string

forceMount boolean false

Name: forceMount
Description: Keeps the group and its items visible whatever the search is.
Type: boolean
Default: false

heading string | Snippet —

Name: heading
Description: The group's heading, which also labels its items.
Type: string | Snippet

data-value

The group's value.

Attribute	Description	-
`data-value`	The group's value.

Item

An item in the command menu. Renders a <div> element.

value string —

Name: value
Description: The item's value. Defaults to its trimmed text content.
Type: string

onclick MouseEventHandler<HTMLDivElement> | null —

Name: onclick
Description: Runs before the item handles the click. Call event.preventDefault() to skip it.
Type: MouseEventHandler<HTMLDivElement> | null

forceMount boolean —

Name: forceMount
Description: Keeps the item visible whatever the search is.
Type: boolean

keywords readonly string[] —

Name: keywords
Description: Extra words the search matches against.
Type: readonly string[]

onSelect function —

Name: onSelect
Description: Called with the item's value on click or Enter.
Type: (value: string) => void

onpointermove PointerEventHandler<HTMLDivElement> | null —

Name: onpointermove
Description: Runs before the item selects itself on pointer movement. Call event.preventDefault() to skip it.
Type: PointerEventHandler<HTMLDivElement> | null

disabled boolean false

Name: disabled
Description: Whether the item ignores the keyboard, the pointer and clicks.
Type: boolean
Default: false

data-selected

"true" when the item is selected, else "false".

data-disabled

"true" when the item is disabled, else "false".

data-value

The item's value.

Attribute	Description	-
`data-selected`	`"true"` when the item is selected, else `"false"`.
`data-disabled`	`"true"` when the item is disabled, else `"false"`.
`data-value`	The item's value.

Separator

A separator between items or groups, removed while searching. Renders a <div> element.

alwaysRender boolean false

Name: alwaysRender
Description: Keeps the separator rendered while searching.
Type: boolean
Default: false

Loading

A progress bar for items that are still loading. Renders a <div> element.

label string 'Loading...'

Name: label
Description: Accessible label for the progress bar.
Type: string
Default: 'Loading...'

progress number —

Name: progress
Description: Loading progress from 0 to 100.
Type: number

Additional types

CommandFilter Hide

type CommandFilter = (value: string, search: string, keywords?: readonly string[]) => number;

CommandGroupDataAttributes Hide

declare namespace CommandGroupDataAttributes {
	/** The group's value. */
	const value: 'data-value';
}

CommandItemDataAttributes Hide

declare namespace CommandItemDataAttributes {
	/** `"true"` when the item is selected, else `"false"`. */
	const selected: 'data-selected';
	/** `"true"` when the item is disabled, else `"false"`. */
	const disabled: 'data-disabled';
	/** The item's value. */
	const value: 'data-value';
}

CommandState Hide

type CommandState = {
	search: string;
	value: string;
	/** How many items match the search, not counting force-mounted ones. 0 until Root mounts. */
	count: number;
	/** The id of the selected item element. */
	selectedId: string | undefined;
};