HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
CommandView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA command palette: a list of commands that opens from anywhere on the page and filters as you type.StableSince 0.1.0NavigationUsageimport'@fusion.dev/helix/command'import'@fusion.dev/helix/option'// Optionimport'@fusion.dev/helix-headless/command'import'@fusion.dev/helix-headless/option'// OptionPreview
API ReferenceRoothelix-commandA command palette: a list of commands that opens from anywhere on the page and filters as you type.
PropTypeDescriptiondefaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.emptyTextstringDefault"No commands"The text shown when the filter matches no commands.filterDelaynumberDefault0How long typing rests before the commands are filtered, in milliseconds, so
a palette filtered on a server sends one helix-filter for a word. 0
filters on every keystroke. See Listbox's filter-delay. The attribute
also takes a CSS time, such as 300ms.filterMatch((text: string, filter: string) => boolean)Whether a command is kept by the filter: a function given the command's
words and the filter, trimmed, that returns true to keep it showing, as
React Aria's Autocomplete takes filter. See Listbox's filterMatch.homeEnd"list"Where Home and End go from the filter field.hotkeystringDefault"mod+k"The key that opens the palette, written as mod+k, shift+p, or k,
in Kbd's chord spelling: mod is Command or Control, ctrl, cmd,
alt and shift the keys they name.inlinebooleanDefaultfalseDraws the palette in the page, where it stands, with no dialog: a search
over a list of commands, as React Aria's Autocomplete is drawn.itemsreadonlyDataOptionItem[]The commands as data, for a palette too long to draw whole: each a value,
which is also its words, or a record with a value, a label and
disabled. Handed to the list, which draws only the commands in sight and
reads no children while it is set. See Listbox's items.labelstringDefault"Commands"Accessible name for the overlay, which has no visible heading.layout"grid"|"stack"How the commands are laid out, as Listbox's layout: grid draws them in
rows and columns, for a palette of icons or emoji, and the arrow keys
follow the rows and the columns. Absent is one command under another.loadErrorstring|nullDefault""What the list says when its commands could not be loaded, such as after a
request to a server fails. Empty, null or no attribute is no error, so
removing the attribute clears it. Passed to the list, which shows it
under any commands there are and tells screen readers.loadingbooleanDefaultfalseWhether the commands are still loading, for a palette that asks a server
for them as the user types.loadingTextstringDefault"Loading"The text shown while the commands load.noResultsTextstringThe text shown when typing hides every one of the commands, where there are
some. Absent, empty-text shows. See Listbox's no-results-text.openbooleanWhether the element is open.pagestringDefault""The page of commands shown, by name: empty for the commands you write
with no slot, or a name for the commands slotted as page: and the
name, such as slot="page:theme".placeholderstringDefault"Search commands"The text shown in the filter field before anything is typed.resultLabelstringWhat a screen reader hears when typing leaves one command, where
results-label should not say it. {count} is the count.resultsLabelstringDefault"{count, plural, one {# command} other {# commands}}"What a screen reader hears when typing narrows the commands. {count} is
how many are left, written in the locale, and each language writes the
forms it has: {count, plural, one {# polecenie} few {# polecenia} many {# poleceń} other {# polecenia}}.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The commands, and any groups of them.emptyWhat the palette shows when typing matches no commands, for content richer than empty-text.errorWhat the palette shows while load-error is set, for content richer than its text.filter-iconReplaces the magnifying glass in the filter field.footerContent under the list, such as the keys that work in the palette.headerContent above the filter field, such as a title or the scope being searched. A heading here does not rename the palette, which label names.loadingWhat the palette shows while the commands load, for content richer than loading-text.no-resultsWhat the palette shows when typing matches no commands, for content richer than no-results-text.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventThe palette is about to close. Cancelable: cancel it to keep it open.helix-before-openHelixBeforeOpenEventThe palette is about to open. Cancelable: cancel it to keep it closed.helix-filterHelixFilterEventFired as the user types, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and filter the commands yourself, for example on a server while loading is set.helix-load-moreHelixLoadMoreEventFired once the list is scrolled within a screen of its end, once for each number of commands, and not while loading is set. Add the next page and set loading while you fetch it.helix-selectHelixSelectEventA command was chosen, with its href where the option is a link. Cancelable: cancel it to keep the palette open, and to keep the browser from following the link.toggleToggleEventThe palette opened or closed. The event carries newState and oldState.
MethodTypeDescriptionrequestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptiondialog-bodyThe dialog's slot for its content, which holds the list. It draws no box until you give it one.dialog-dismissThe dialog's close control, drawn when the dialog is dismissible.dialog-dismiss-markThe glyph on the dialog's close control, where none is slotted.dialog-footerThe dialog's slot for its actions, which holds the footer row. It draws no box until you give it one.dialog-headerThe dialog's slot for its title. It draws no box until you give it one.dialog-surfaceThe box of the dialog the palette opens in, forwarded from Dialog.footerThe row under the list.listboxThe listbox inside the palette.listbox-emptyThe text shown when the filter matches no commands.listbox-errorThe text shown while load-error is set.listbox-feedbackThe listbox's error message.listbox-filter-iconThe icon beside the filter field.listbox-filter-markThe default icon beside the filter field, drawn when no icon is slotted.listbox-hintHelp text under the list.listbox-itemsThe list of commands.listbox-labelThe label above the list.listbox-liveThe listbox's live part, a live region that holds the empty and loading text, and how many commands typing left, for screen readers.listbox-loadingThe text shown while the commands are loading.listbox-searchThe region that holds the filter field.listbox-search-fieldThe filter field.liveThe region a screen reader announces the page shown from, by the words of the command that opens it, drawn once there is one to say. Visually hidden in the styled tier.
CSS PropertyDescription--command-list-sizeHow tall the list grows before it scrolls.--command-sizeHow wide the palette is. Defaults to 40rem.
Custom stateDescriptionemptyThe list shows no commands: there are none, or typing hid every one.errorWhile load-error is set.loadingWhile loading is set.no-resultsTyping hid every one of the commands, where there are some.openWhile the palette is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-commandA command palette: a list of commands that opens from anywhere on the page and filters as you type.
PropTypeDescriptiondefaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.emptyTextstringDefault"No commands"The text shown when the filter matches no commands.filterDelaynumberDefault0How long typing rests before the commands are filtered, in milliseconds, so
a palette filtered on a server sends one helix-filter for a word. 0
filters on every keystroke. See Listbox's filter-delay. The attribute
also takes a CSS time, such as 300ms.filterMatch((text: string, filter: string) => boolean)Whether a command is kept by the filter: a function given the command's
words and the filter, trimmed, that returns true to keep it showing, as
React Aria's Autocomplete takes filter. See Listbox's filterMatch.homeEnd"list"Where Home and End go from the filter field.hotkeystringDefault"mod+k"The key that opens the palette, written as mod+k, shift+p, or k,
in Kbd's chord spelling: mod is Command or Control, ctrl, cmd,
alt and shift the keys they name.inlinebooleanDefaultfalseDraws the palette in the page, where it stands, with no dialog: a search
over a list of commands, as React Aria's Autocomplete is drawn.itemsreadonlyDataOptionItem[]The commands as data, for a palette too long to draw whole: each a value,
which is also its words, or a record with a value, a label and
disabled. Handed to the list, which draws only the commands in sight and
reads no children while it is set. See Listbox's items.labelstringDefault"Commands"Accessible name for the overlay, which has no visible heading.layout"grid"|"stack"How the commands are laid out, as Listbox's layout: grid draws them in
rows and columns, for a palette of icons or emoji, and the arrow keys
follow the rows and the columns. Absent is one command under another.loadErrorstring|nullDefault""What the list says when its commands could not be loaded, such as after a
request to a server fails. Empty, null or no attribute is no error, so
removing the attribute clears it. Passed to the list, which shows it
under any commands there are and tells screen readers.loadingbooleanDefaultfalseWhether the commands are still loading, for a palette that asks a server
for them as the user types.loadingTextstringDefault"Loading"The text shown while the commands load.noResultsTextstringThe text shown when typing hides every one of the commands, where there are
some. Absent, empty-text shows. See Listbox's no-results-text.openbooleanWhether the element is open.pagestringDefault""The page of commands shown, by name: empty for the commands you write
with no slot, or a name for the commands slotted as page: and the
name, such as slot="page:theme".placeholderstringDefault"Search commands"The text shown in the filter field before anything is typed.resultLabelstringWhat a screen reader hears when typing leaves one command, where
results-label should not say it. {count} is the count.resultsLabelstringDefault"{count, plural, one {# command} other {# commands}}"What a screen reader hears when typing narrows the commands. {count} is
how many are left, written in the locale, and each language writes the
forms it has: {count, plural, one {# polecenie} few {# polecenia} many {# poleceń} other {# polecenia}}.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The commands, and any groups of them.emptyWhat the palette shows when typing matches no commands, for content richer than empty-text.errorWhat the palette shows while load-error is set, for content richer than its text.filter-iconReplaces the magnifying glass in the filter field.footerContent under the list, such as the keys that work in the palette.headerContent above the filter field, such as a title or the scope being searched. A heading here does not rename the palette, which label names.loadingWhat the palette shows while the commands load, for content richer than loading-text.no-resultsWhat the palette shows when typing matches no commands, for content richer than no-results-text.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventThe palette is about to close. Cancelable: cancel it to keep it open.helix-before-openHelixBeforeOpenEventThe palette is about to open. Cancelable: cancel it to keep it closed.helix-filterHelixFilterEventFired as the user types, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and filter the commands yourself, for example on a server while loading is set.helix-load-moreHelixLoadMoreEventFired once the list is scrolled within a screen of its end, once for each number of commands, and not while loading is set. Add the next page and set loading while you fetch it.helix-selectHelixSelectEventA command was chosen, with its href where the option is a link. Cancelable: cancel it to keep the palette open, and to keep the browser from following the link.toggleToggleEventThe palette opened or closed. The event carries newState and oldState.
MethodTypeDescriptionrequestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptiondialog-bodyThe dialog's slot for its content, which holds the list. It draws no box until you give it one.dialog-dismissThe dialog's close control, drawn when the dialog is dismissible.dialog-dismiss-markThe glyph on the dialog's close control, where none is slotted.dialog-footerThe dialog's slot for its actions, which holds the footer row. It draws no box until you give it one.dialog-headerThe dialog's slot for its title. It draws no box until you give it one.dialog-surfaceThe box of the dialog the palette opens in, forwarded from Dialog.footerThe row under the list.listboxThe listbox inside the palette.listbox-emptyThe text shown when the filter matches no commands.listbox-errorThe text shown while load-error is set.listbox-feedbackThe listbox's error message.listbox-filter-iconThe icon beside the filter field.listbox-filter-markThe default icon beside the filter field, drawn when no icon is slotted.listbox-hintHelp text under the list.listbox-itemsThe list of commands.listbox-labelThe label above the list.listbox-liveThe listbox's live part, a live region that holds the empty and loading text, and how many commands typing left, for screen readers.listbox-loadingThe text shown while the commands are loading.listbox-searchThe region that holds the filter field.listbox-search-fieldThe filter field.liveThe region a screen reader announces the page shown from, by the words of the command that opens it, drawn once there is one to say. Visually hidden in the styled tier.
Custom stateDescriptionemptyThe list shows no commands: there are none, or typing hid every one.errorWhile load-error is set.loadingWhile loading is set.no-resultsTyping hid every one of the commands, where there are some.openWhile the palette is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionEventsThe events the palette sends as it opens, runs a command, and closes. The palette holds no value.HotkeyA palette that opens with a keyboard shortcut from anywhere on the page.OpenThe palette as it looks the moment it opens, before anything is typed.PreviewA command palette open, with its list already filtered by what is typed.PreviewA command palette open, with its list already filtered by what is typed.Two DestinationsRows with a second destination, taken when the modifier key is held.