CommandPalette

CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Command Palette

CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.

Prop	Type	Default	Description
isOpen *	boolean		Whether the command palette dialog is visible.
onOpenChange *	(isOpen: boolean) => void		Called when the palette visibility changes.
searchSource *	SearchSource<T>		Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.
input	ReactNode	<CommandPaletteInput />	Input slot. Defaults to CommandPaletteInput with standard behavior.
footer	ReactNode	<CommandPaletteFooter />	Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.
renderItem	(item: T, isSelected: boolean) => ReactNode		Per-item render function for non-interactive presentation content such as labels, icons, descriptions, and shortcut hints. Do not return buttons or links inside the option. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.
emptySearchText	ReactNode	'No results'	Content shown when a search query returns no results.
emptyBootstrapText	ReactNode	'Type to search'	Content shown when there is no search query and bootstrap() returns nothing.
value	string		Controlled selected value for picker mode.
onValueChange	(value: string) => void		Called when the selected value changes in picker mode.
label	string	'Command palette'	Accessible label for the command palette dialog.
width	number \| string	640	Width of the dialog.
maxHeight	number \| string	480	Maximum height of the dialog.
isInline	boolean	false	Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.

Usage guidance

Provide a searchSource with bootstrap results so users see useful options before typing.
Use auxiliaryData.group on items to automatically organize results into labeled sections.
Provide a specific label when more than one command palette can appear in the same product surface.
Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.
Avoid: Intercept query-field keyboard events without preserving active IME composition and native Home/End caret movement.
Avoid: Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.
Avoid: Add too many groups or items; curate results to keep the palette fast and scannable.

Theming API

{
  "targets": [
    {
      "className": "astryx-command-palette-empty"
    },
    {
      "className": "astryx-command-palette-footer"
    },
    {
      "className": "astryx-command-palette-group"
    },
    {
      "className": "astryx-command-palette-group-heading"
    },
    {
      "className": "astryx-command-palette-input"
    },
    {
      "className": "astryx-command-palette-item"
    },
    {
      "className": "astryx-command-palette-list"
    }
  ]
}

CommandPaletteInput

CommandPaletteList

CommandPaletteItem

CommandPaletteGroup

CommandPaletteFooter

CommandPaletteEmpty

Anatomy

Dialog: Modal surface that contains the command palette.
Input: Search region containing the query field and its supporting visuals.
Search glyph: Search symbol rendered by Icon in the default Input.
Query field: Native text field used to enter a search query.
Loading spinner: Spinner shown in the default Input while a search is pending.
List: Scrollable results container: a listbox while selectable results exist, otherwise the Empty state as plain content.
Item: Selectable command result rendered inside the List.
Group: Optional collection of Items that share a heading.
Group heading: Visible heading rendered for a Group.
Empty: Message shown when the current result set is empty.
Footer: Footer region for default keyboard guidance or caller-provided content.
Keyboard shortcut: Painted key badges rendered by Kbd in the default Footer guidance.

Command Palette Empty

Empty state display for the results area. Rendered automatically by CommandPalette for no-results and no-query states.

Prop	Type	Default	Description
children *	ReactNode		Message or content to display.

CommandPalette renders CommandPaletteFooter automatically. Pass a CommandPaletteFooter to the footer slot only when replacing the default guidance.

Prop	Type	Default	Description
children	ReactNode		Custom footer content. When omitted, renders default keyboard hints via Kbd.
xstyle	StyleXStyles		StyleX styles for layout customization. Must be a stylex.create() value.

Theming API

{
  "targets": [
    {
      "className": "astryx-command-palette-footer"
    }
  ]
}

Anatomy

Footer: Supporting region that presents default guidance or caller-provided footer content.
Keyboard shortcut: Default Kbd badges for navigation, selection, and dismissal.

Command Palette Group

Visual grouping with a heading label. Place inside CommandPaletteList.

Prop	Type	Description
heading *	string	Group heading text.
children *	ReactNode	CommandPaletteItem children.
xstyle	StyleXStyles	StyleX styles for layout customization. Must be a stylex.create() value.

Command Palette Input

Use CommandPaletteInput inside CommandPalette for a popup-backed command query, or as an independent search field when no result popup is present.

Prop	Type	Default	Description
placeholder	string	'Search…'	Placeholder text for the input.
label	string		Accessible label for the query field, announced by screen readers. Defaults to the translated "Search commands"; the placeholder is never used as the name.
hasAutoFocus	boolean	true	Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.
endContent	ReactNode		Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.
value	string		Search value. When omitted inside CommandPalette, reads from context.
onValueChange	(value: string) => void		Called when search value changes. When omitted inside CommandPalette, writes to context.
xstyle	StyleXStyles		StyleX styles for layout customization. Must be a stylex.create() value.

Usage guidance

Pass a concise label that identifies what can be searched when "Search commands" does not describe it; the placeholder is never the field's name.
Use endContent for short supporting controls or shortcut hints at the trailing edge.
Avoid: Override combobox role or popup state. CommandPaletteInput owns those semantics when connected to CommandPalette.

Theming API

{
  "targets": [
    {
      "className": "astryx-command-palette-input"
    }
  ]
}

Anatomy

Input: The surrounding inline layout for the search glyph, query field, and trailing content.
Search glyph: A decorative search icon before the query field.
Query field: The native text field. It is a searchbox when standalone without popup attributes and a combobox when popup relationships are supplied or CommandPalette context is present.
Loading spinner: A delayed pending indicator shown before trailing content while search is busy.
Trailing content: Caller-provided supporting content such as a clear control or shortcut hint.

Command Palette Item

Use CommandPaletteItem for one non-interactive result row inside CommandPaletteList or CommandPaletteGroup. CommandPalette owns the composite keyboard model; standalone items expose only their explicit visual state and pointer activation.

Prop	Type	Default	Description
value *	string		Unique value used for item identity, highlight lookup, and selection.
children *	ReactNode		Non-interactive item content such as a label, icon, description, or keyboard shortcut.
onSelect	(value: string) => void		Called after this item is activated by pointer. Keyboard selection in CommandPalette reports through CommandPalette onValueChange.
isHighlighted	boolean	false	Whether this item is the active keyboard result. Derived from context when omitted inside CommandPalette.
isSelected	boolean	false	Whether this item represents the selected value in picker mode.
isDisabled	boolean	false	Whether the item is unavailable and suppresses pointer activation.
xstyle	StyleXStyles		StyleX styles for layout customization. Must be a stylex.create() value.

Usage guidance

Keep each value unique within the result list so highlight, active-descendant identity, and selection resolve to the same item.
Use non-interactive child content such as icons, descriptions, and shortcut hints; activate the option itself instead of nesting buttons or links.
Avoid: Treat isHighlighted as selection. Highlight is the active keyboard result; isSelected represents the chosen value.

Theming API

{
  "targets": [
    {
      "className": "astryx-command-palette-item"
    }
  ]
}

Anatomy

Item: The option root that carries selection, disabled, item identity, interaction, and theme state.
Content: Caller-provided non-interactive label and supporting presentation.

Command Palette List

Scrollable results container. Renders as a listbox standalone, and inside CommandPalette while selectable results exist. Contains CommandPaletteItem and CommandPaletteGroup children.

Prop	Type	Default	Description
children *	ReactNode		Items, groups, and empty states.
label	string	'Commands'	Accessible label for the listbox.
xstyle	StyleXStyles		StyleX styles for layout customization. Must be a stylex.create() value.

CommandPalette

CommandPalette

Installation

Command Palette

Usage guidance

Theming API

CommandPaletteInput

CommandPaletteList

CommandPaletteItem

CommandPaletteGroup

CommandPaletteFooter

CommandPaletteEmpty

Anatomy

Command Palette Empty

Command Palette Footer

Theming API

Anatomy

Command Palette Group

Command Palette Input

Usage guidance

Theming API

Anatomy

Command Palette Item

Usage guidance

Theming API

Anatomy

Command Palette List

Examples