Command
A searchable list of commands, inline or as a command palette in a dialog, filtered as the reader types.
Command is a list of commands with a search field: typing filters the list, the arrow keys move
and Enter chooses. Inline, it is a filterable menu; in Command, it is a command palette
that jumps to any page or action. It is built on cmdk, whose props it
passes through. For picking a form value from a list, use a combobox.
Command palette
Search for a page or an action.
Chosen: nothing yet
// apps/docs/examples/ui/command.tsx'use client';
import {useState} from 'react';import {FileTextIcon, SettingsIcon, UsersIcon} from 'lucide-react';
import {Button} from '@workspace/active-ui/components/primitives/button';import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator,} from '@workspace/active-ui/components/primitives/command';
const PAGES = [ {label: 'Schemes', icon: FileTextIcon}, {label: 'Participants', icon: UsersIcon}, {label: 'Settings', icon: SettingsIcon},];const ACTIONS = ['Create a scheme', 'Import participants', 'Send statements'];
function Palette({onChoose}: {onChoose: (value: string) => void}) { return ( <> <CommandInput placeholder="Type a page or an action" /> <CommandList> <CommandEmpty>Nothing matches.</CommandEmpty> <CommandGroup heading="Go to"> {PAGES.map(({label, icon: Icon}) => ( <CommandItem key={label} onSelect={() => onChoose(label)}> <Icon aria-hidden /> {label} </CommandItem> ))} </CommandGroup> <CommandSeparator /> <CommandGroup heading="Actions"> {ACTIONS.map((label) => ( <CommandItem key={label} onSelect={() => onChoose(label)}> {label} </CommandItem> ))} </CommandGroup> </CommandList> </> );}
/** * A searchable list of commands: inline, as a filterable menu on the page, * and in a dialog, as a command palette. Typing filters by fuzzy match; the * arrow keys and Enter choose. */export default function CommandExample() { const [open, setOpen] = useState(false); const [chosen, setChosen] = useState('nothing yet'); return ( <div className="flex w-full max-w-sm flex-col items-center gap-4"> <Command label="Pages and actions" className="w-full rounded-lg border shadow-xs" > <Palette onChoose={setChosen} /> </Command> <Button variant="outline" onClick={() => setOpen(true)}> Open the command palette </Button> <CommandDialog open={open} onOpenChange={setOpen} title="Command palette" description="Search for a page or an action." > <Command label="Pages and actions"> <Palette onChoose={(value) => { setChosen(value); setOpen(false); }} /> </Command> </CommandDialog> <p className="text-muted-foreground text-sm" aria-live="polite"> Chosen: {chosen} </p> </div> );}Usage#
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList,} from '@workspace/active-ui/components/primitives/command';
<Command label="Pages and actions"> <CommandInput placeholder="Type a page or an action" /> <CommandList> <CommandEmpty>Nothing matches.</CommandEmpty> <CommandGroup heading="Go to"> <CommandItem onSelect={() => go('/schemes')}>Schemes</CommandItem> </CommandGroup> </CommandList></Command>;Anatomy#
Command: the search state.labelnames it for assistive technology;filterreplaces the fuzzy match;shouldleaves filtering to you, for results from a server.Filter={false} Command: the search field, with its icon.Input CommandwithList Command(itsGroup heading),Command(Item on,Select value,keywordsfor extra search words,disabled),CommandandSeparator Command, shown when nothing matches.Empty Command: shows a key combination beside an item; binding it is your application's work.Shortcut Command: a dialog for a palette. Put aDialog Commandinside it.
What your application provides#
labelonCommand, andtitleanddescriptiononCommand: they name and describe the palette for screen readers (visually hidden, required).Dialog closeadds a close button; without it,Label Escapeand a choice close the dialog.What each item does in
on, and closing the dialog afterwards.Select A way to open the palette, such as a button, and a keyboard shortcut if you bind one.
Accessibility and keyboard#
The input is a
role="combobox"that controls the list; the list is alistboxwithoptions.↓and↑move through the matching items,Enterruns the highlighted one.In the dialog, the focus starts in the input and returns to the opening element on close.
API#
Command#
Import from @workspace/
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, children, default, disable, filter, label, loop, on, should, value, vim.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandDialog#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
ReactNode
- Type
string
What the palette is for, read with the name; visually hidden.
- Type
string
The name of the palette for screen readers; visually hidden.
- Type
boolean
Whether the dialog is currently open.
- Type
boolean- Default
false
Whether the dialog is initially open.
To render a controlled dialog, use the open prop instead.
- Type
string
Classes for the dialog panel.
- Type
string
Name of the close button. Omitted? Then the panel shows no close button -- the dialog closes with Escape and with a choice from the list.
- Type
string | null
ID of the trigger that the dialog is associated with. This is useful in conjunction with the default prop to create an initially open dialog.
- Type
boolean- Default
false
Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
- Type
DialogHandle<unknown>
A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
- Type
"trap-focus" | boolean - Default
true
Determines if the dialog enters a modal state when open.
true: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.false: user interaction with the rest of the document is allowed.'trap-: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled.focus'
When modal is true or 'trap-, render <Dialog. inside <Dialog. so touch screen readers can escape the popup.
- Type
string | null
ID of the trigger that the dialog is associated with. This is useful in conjunction with the open prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).
- Type
RefObject<…>
A ref to imperative actions.
unmount: Ends the closing phase of the dialog after an externally controlled closing animation finishes. CallpreventinUnmount On Close() onfirst, otherwise the dialog completes closing on its own. Whether it leaves the DOM is decided byOpen Change keepon the portal.Mounted close: Closes the dialog imperatively when called.
Events
Called by the component when something happens.
- Type
(open, eventDetails) => void
Event handler called when the dialog is opened or closed.
- Type
(open: boolean) => void
Event handler called after any animations complete when the dialog is opened or closed.
Takes only the props listed.
Other parts#
CommandInput
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, on, value.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandList
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, children, label.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandEmpty
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, children.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandGroup
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, children, force, heading, value.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandItem
No props of its own.
Also takes the props of cmdk, unchanged and documented there: as, children, disabled, force, keywords, on, value.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
CommandSeparator
No props of its own.
Also takes the props of cmdk, unchanged and documented there: always, as.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Parts that take only their element’s attributes
Command: the attributes of aShortcut <span>, with className and ref.
This page adapts the Command documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.