# CommandPalette

- Page: https://jiguang132.com/resources/astryx/docs/command-palette
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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. |

## Command Palette Footer

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

```json
{
  "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 | Default | 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

```json
{
  "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

```json
{
  "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. |


## Examples

- Command Palette Empty: Command palette empty state shown when no commands are available.
- Command Palette Footer: Command palette footer with custom tip content.
- Command Palette Group: Command palette groups in both data-driven (auxiliaryData.group) and composed (CommandPaletteGroup + CommandPaletteItem) forms.
- Command Palette Input: Command palette search input with a custom placeholder and a keyboard shortcut hint in the endContent slot.
- Command Palette Item: Command palette items with custom content via renderItem and as composed CommandPaletteItem with icons, highlighted, selected, and disabled states.
- Command Palette List: Scrollable command palette list with grouped items, including a highlighted item, composed without a full CommandPalette.
- Command Palette: Basic command palette with static items and keyboard navigation.
- CommandPalette — Async Search: Server-side search with loading spinner and custom empty states.
- CommandPalette — Grouped: Command palette with items grouped via auxiliaryData.group.
- CommandPalette — Custom Footer: Command palette with a custom footer tip message.
- CommandPaletteEmpty — Basic: A command palette with no results, showing a custom empty message via emptyBootstrapText. Use to explain why the palette is empty and what the user can do next.
- CommandPaletteFooter — Basic: A command palette footer with no children, rendering the built-in keyboard navigation hints. Use CommandPaletteFooter without content to get the default arrow-key, Enter, and Esc hints below the results list.
- CommandPaletteGroup — Basic: Command palette items organized under group headings using the composed CommandPaletteGroup form. Use to separate related commands into labeled sections.
- CommandPaletteInput — With End Content: Custom placeholder and a keyboard shortcut badge in the trailing slot via endContent.
- CommandPaletteItem — Basic: Selectable command palette items inside a CommandPaletteList, including highlighted and disabled states. Use when composing a palette manually instead of a search source.
- CommandPaletteList — Item States: Flat list showing the highlighted, selected, and disabled item states. Use CommandPaletteGroup to add section headings.
- CommandPalette — Picker Mode: Single-value picker with persistent selection and check indicator.
- CommandPalette — Rich Items: Custom item rendering with icons, keyboard shortcuts, and keyword search.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt