Command

A searchable list of commands, often opened with a keyboard shortcut.

Usage

Code
import { Command, Portal, useCommandCollection } from '@leverui/components';
Code
<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.

Code
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 onSelect and closes the dialog. Set closeOnSelect: false on the item or on Root to keep it open.
  • Holding ⌘, Ctrl, Shift, or Alt while selecting keeps the dialog open. onSelect gets the keys as modifiers.
  • The query clears after the dialog closes.
  • Command.DialogBackdrop is optional.
  • disabled: true on 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.

Code
<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.

Code
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
RS
Rhea Solano
Project
Auth revamp
Labels
Bug

Shortcuts

S

Change status...

P

Change priority...

A

Assign to...

L

Add labels...

ShiftP

Move to project...

Ctrl.

Copy issue ID

CtrlShift,

Copy issue URL

Code
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().pages is 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

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.

BugAccessibility

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.

Code
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

PropDefaultTypeDescription
command—UseCommandCollectionReturn<T>Collection from useCommandCollection. Optional inside Command.Provider.
collection—ListCollection<T>Plain list collection, without useCommandCollection.
sizemd'sm' | 'md' | 'lg'Component size. Responsive.
colorPalettegrayColor palette nameColor palette.
loadingfalseboolean | undefinedShow Spinner and Loading; mark the panel and indicator as loading.
closeOnSelecttrueboolean | undefinedClose on select.
onSelect—(details: CommandSelectionDetails) => voidCalled on select, after the item's own onSelect.
onClose—() => voidCalled when selecting an ordinary action closes the dialog.
inputValue—stringControlled input value. Prefer query on useCommandCollection.
defaultInputValue—stringInitial input value.
onInputValueChange—(details: InputValueChangeDetails) => voidCalled on input change, after the query updates.
highlightedValue—stringControlled value of the highlighted item.
defaultHighlightedValue—stringValue of the item highlighted at the start.
onHighlightChange—(details: HighlightChangeDetails) => voidCalled when the highlighted item changes.
navigate—(details: NavigateDetails) => voidNavigate to the selected item.
scrollToIndexFn—(details: ScrollToIndexDetails) => voidScroll the list to an index.
id—stringUnique id for the component.
ids—Element ID mapIds for the component's elements.
unstyled—booleanTurn 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

PropDefaultTypeDescription
item—TCollection item to render.
asdivNative tagHTML tag to render.
asChild—Solid render functionRender 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

PropDefaultTypeDescription
highlight—booleanBold the characters that match the query.
asspanNative tagHTML tag to render.
asChild—Solid render functionRender 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.

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.