Command
A searchable list of commands, often opened with a keyboard shortcut.
Usage
import { Command, Portal, useCommandCollection } from '@leverui/components';
<Command.Provider>
<Command.Dialog>
<Command.DialogTrigger />
<Portal>
<Command.DialogBackdrop />
<Command.DialogContent>
<Command.Root>
<Command.Label />
<Command.Control>
<Command.Indicator />
<Command.Input />
<Command.ClearTrigger />
</Command.Control>
<Command.List>
<Command.Loading />
<Command.ItemGroup>
<Command.ItemGroupLabel />
<Command.Item>
<Command.ItemText />
<Command.ItemCommand />
</Command.Item>
</Command.ItemGroup>
<Command.Separator />
<Command.Empty />
</Command.List>
<Command.Footer />
</Command.Root>
</Command.DialogContent>
</Portal>
</Command.Dialog>
</Command.Provider>
useCommandCollection ranks the items as you type. Command.Provider shares
the result with the dialog and the root.
const command = useCommandCollection({ initialItems: commands });
<Command.Provider value={command}>
<Command.Dialog>
<Portal>
<Command.DialogBackdrop />
<Command.DialogContent>
<Command.Root>{/* ... */}</Command.Root>
</Command.DialogContent>
</Portal>
</Command.Dialog>
</Command.Provider>;
- Selecting an item runs its
onSelectand closes the dialog. SetcloseOnSelect: falseon the item or onRootto keep it open. - Holding ⌘, Ctrl, Shift, or Alt while selecting keeps the dialog open.
onSelectgets the keys asmodifiers. - The query clears after the dialog closes.
Command.DialogBackdropis optional.disabled: trueon an item shows it but stops it from running.- No default shortcut opens the dialog. Bind ⌘K with your app's own hotkey tool, as the Hotkeys example does.
Command only runs actions. To pick and keep a value, use Combobox or Listbox.
Examples
Inline
Render Command.Root without a dialog and pass the collection with the command prop. Add a Command.Label to name the search, visually hidden if needed. In a dialog, the hidden title from Command.DialogContent names it instead.
Groups
Pass groupBy to useCommandCollection. Items are ranked within each group, and the group order stays fixed while you type.
Keywords
Add keywords to an item so other words find it, like "preferences" for Settings. Keyword matches rank just below label matches.
Highlight Matches
Set highlight on ItemText to bold the matched characters, including fuzzy and camelCase matches.
<Command.ItemText highlight>{item.label}</Command.ItemText>
Controlled Search
Pass query and onQueryChange to keep the query in your own state, for example to sync it with the URL.
Try
Query: empty
Prefix Search
Type >, @, or # first to search only commands, people, or channels. Backspace on an empty input clears the scope.
Tabs
Filter the items by the active tab.
Async Content
Pass load to fetch items as you type. Stale requests are cancelled, and Loading and Empty never show at the same time.
Load More
Return { items, cursor } from load to page through results. Call command().loadMore() when the user reaches the end of the list and command().hasMore is true.
Bring Your Own Data
To fetch with your own data layer, such as TanStack Query, control the query and pass the results in. Set filter: null so server results show as returned.
const [query, setQuery] = createSignal('');
const people = useQuery(() => ({
queryKey: ['people', query()],
queryFn: () => searchPeople(query()),
}));
const command = useCommandCollection(() => ({
initialItems: people.data ?? [],
query: query(),
onQueryChange: setQuery,
filter: null,
}));
<Command.Root command={command} loading={people.isFetching}>
{/* ... */}
</Command.Root>;
Nested
Give an item a parent to put it on that item's page. Nothing else changes in the markup.
- Status
- In progress
- Priority
- High
- Assignee
- RSRhea Solano
- Project
- Auth revamp
- Labels
- Bug
Shortcuts
Change status...
Change priority...
Assign to...
Add labels...
Move to project...
Copy issue ID
Copy issue URL
const command = useCommandCollection({
initialItems: [
{ label: 'Change status...', value: 'status' },
{ label: 'Done', value: 'status:done', parent: 'status' },
],
deepSearch: true,
});
- Selecting an item with children opens its page.
- Escape goes back to the previous page, then closes the dialog.
- Backspace on an empty input goes up a page.
- Going back restores the query and highlights the item you came from.
command().pagesis the trail of open pages, for a breadcrumb.- With
deepSearch, a query also matches items in nested pages.command().getPath(item)returns where a match lives. - To open a page directly, such as from a shortcut, call
command().reset('status')before opening the dialog. Escape then closes it.
Async Pages
Set page: true on an item to open a page that loads its own items. load receives the current page and reloads when it changes.
Input Pages
Build a page's items from the query, such as "Rename to …" or "Invite by email".
Fix login redirect loop on Safari
No invites yet
Hotkeys
Register the same items with useHotkeys so their shortcuts work while the menu is closed. Format them per platform with useFormatHotkey.
Try G then I, or C, with the menu closed
Store
Use useCommand with Command.RootProvider to work with the command's state from outside, such as controlling the dialog from a ⌘K shortcut.
Last search: None
Links
Render items as anchors with asChild, so links open with a click, a middle-click, or Enter. ⌘+Enter or Ctrl+Enter opens the link in a new tab, like ⌘+click.
Recent Items
Store recently used commands and show them in their own group.
Toggle Items
Set closeOnSelect={false} and toggle values in onSelect to pick several items without closing.
Footer Actions
Show shortcut hints or actions below the list with Footer.
Empty State
Customize what Empty shows when nothing matches.
Virtualized
Virtualize the list for large datasets. Pass a deferred copy of the query as filterQuery so typing stays responsive. Enter still runs the top match for what you typed.
const [query, setQuery] = createSignal('');
const deferredQuery = createDeferred(query);
const command = useCommandCollection(() => ({
initialItems,
query: query(),
onQueryChange: setQuery,
filterQuery: deferredQuery(),
}));
Sizes
size on Command.Root sets the density. size on Command.Dialog sets the width.
Props
Every part takes as, an HTML tag, and asChild, a Solid function that
renders your own element with the part's props.
Root
| Prop | Default | Type | Description |
|---|---|---|---|
command | — | UseCommandCollectionReturn<T> | Collection from useCommandCollection. Optional inside Command.Provider. |
collection | — | ListCollection<T> | Plain list collection, without useCommandCollection. |
size | md | 'sm' | 'md' | 'lg' | Component size. Responsive. |
colorPalette | gray | Color palette name | Color palette. |
loading | false | boolean | undefined | Show Spinner and Loading; mark the panel and indicator as loading. |
closeOnSelect | true | boolean | undefined | Close on select. |
onSelect | — | (details: CommandSelectionDetails) => void | Called on select, after the item's own onSelect. |
onClose | — | () => void | Called when selecting an ordinary action closes the dialog. |
inputValue | — | string | Controlled input value. Prefer query on useCommandCollection. |
defaultInputValue | — | string | Initial input value. |
onInputValueChange | — | (details: InputValueChangeDetails) => void | Called on input change, after the query updates. |
highlightedValue | — | string | Controlled value of the highlighted item. |
defaultHighlightedValue | — | string | Value of the item highlighted at the start. |
onHighlightChange | — | (details: HighlightChangeDetails) => void | Called when the highlighted item changes. |
navigate | — | (details: NavigateDetails) => void | Navigate to the selected item. |
scrollToIndexFn | — | (details: ScrollToIndexDetails) => void | Scroll the list to an index. |
id | — | string | Unique id for the component. |
ids | — | Element ID map | Ids for the component's elements. |
unstyled | — | boolean | Turn off the Lever UI styles. |
No props for hotkeys or for keeping a selection. Add shortcuts with
useHotkeys, as in Hotkeys. Keep a selection with closeOnSelect={false} and
onSelect, as in Toggle Items.
RootProvider
Pass the machine from useCommand to Command.RootProvider as value. Also
takes the appearance props above.
Label
Renders a label. Accepts as and asChild.
Input
Renders an input. Accepts as and asChild.
Control
Renders a div. Accepts as and asChild.
Indicator
Renders a div. Accepts as and asChild.
List
Renders a div. Accepts as and asChild.
Loading
Renders a div. Accepts as and asChild.
Item
| Prop | Default | Type | Description |
|---|---|---|---|
item | — | T | Collection item to render. |
as | div | Native tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the item's props. |
Set onSelect and closeOnSelect on the item's data in initialItems. Its
onSelect runs before the Root one, and its closeOnSelect overrides Root's.
ItemText
| Prop | Default | Type | Description |
|---|---|---|---|
highlight | — | boolean | Bold the characters that match the query. |
as | span | Native tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the text's props. |
ItemGroup
Renders a div. Accepts as and asChild.
ItemGroupLabel
Renders a div. Accepts as and asChild.
ItemCommand
Renders a kbd. Accepts as and asChild.
Empty
Renders a div. Accepts as and asChild.
Separator
Renders a div. Accepts as and asChild.
Footer
Renders a div. Accepts as and asChild.
Customize with CSS
Set --leverui-command-* variables or style the .leverui-command__* part
classes. Command.DialogContent has the class
.leverui-command-dialog__content. Its hidden title and description use
.leverui-command-dialog__accessible-label and name the dialog, input, and
list. unstyled on the root turns off the Lever UI styles.