An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file CommandPalette.tsx
* @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource,
* useCombobox, useAnnounce, useAnnounceRenderedText
* @output Exports CommandPalette root component and props
* @position Core root component; dialog shell with searchSource-driven items
*
* SYNC: When modified, update these files to stay in sync:
* - /apps/storybook/stories/CommandPalette.stories.tsx
* - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
*/
import {
useCallback,
useEffect,
useId,
useMemo,
useOptimistic,
useRef,
useState,
useTransition,
type ReactNode,
} from 'react';
import {Dialog} from '../Dialog';
import {Layout, LayoutHeader, LayoutContent, LayoutFooter} from '../Layout';
import type {SearchSource, SearchableItem} from '../Typeahead';
import {useCombobox} from '../Selector';
import type {SelectorOptionData} from '../Selector';
import {CommandPaletteContext} from './CommandPaletteContext';
import {BusyStartSettleContext} from './busyStartSettle';
import {CommandPaletteList} from './CommandPaletteList';
import {CommandPaletteItem} from './CommandPaletteItem';
import {CommandPaletteGroup} from './CommandPaletteGroup';
import {CommandPaletteInput} from './CommandPaletteInput';
import {CommandPaletteFooter} from './CommandPaletteFooter';
import {CommandPaletteEmpty} from './CommandPaletteEmpty';
import type {BaseProps} from '../BaseProps';
import {useAnnounce} from '../hooks/useAnnounce';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/CommandPalette/CommandPalette.generated';
registerEnglishFallback(english);
export interface CommandPaletteProps<
T extends SearchableItem = SearchableItem,
> extends Omit<BaseProps<HTMLDialogElement>, 'onChange'> {
ref?: React.Ref<HTMLDialogElement>;
/** Whether the command palette is open. */
isOpen: boolean;
/**
* Renders command palette content inline without modal behavior.
* Suppresses input auto-focus and initial highlighted-item auto-scroll.
* For documentation previews and showcases only.
* @default false
*/
isInline?: boolean;
/** Called when the command palette visibility changes. */
onOpenChange: (isOpen: boolean) => void;
/**
* Search source providing items. Implements `search(query)` and `bootstrap()`.
* Same interface as Typeahead's searchSource.
* Use `createStaticSource` for simple static lists.
*/
searchSource: SearchSource<T>;
/**
* The search input slot.
* @default <CommandPaletteInput />
*/
input?: ReactNode;
/**
* The footer slot.
* @default <CommandPaletteFooter />
*/
footer?: ReactNode;
/**
* Per-item render function. Receives the item and whether it is currently selected.
* Return non-interactive presentation content; buttons and links cannot be
* nested inside the rendered option. Auto-grouping by `auxiliaryData.group`
* is preserved.
* When omitted, renders each item's `label` text.
*/
renderItem?: (item: T, isSelected: boolean) => ReactNode;
/**
* Content shown when a search query returns no results.
* @default 'No results'
*/
emptySearchText?: ReactNode;
/**
* Content shown when there is no search query and bootstrap() returns nothing.
* @default 'Type to search'
*/
emptyBootstrapText?: ReactNode;
/** Controlled selected value (for picker mode). */
value?: string;
/** Called when the selected value changes. */
onValueChange?: (value: string) => void;
/**
* Accessible label for the command palette dialog.
* @default 'Command palette'
*/
label?: string;
/**
* Width of the command palette dialog.
* @default 640
*/
width?: number | string;
/**
* Maximum height of the command palette dialog.
* @default 480
*/
maxHeight?: number | string;
}
function getGroup(item: SearchableItem): string | undefined {
const aux = item.auxiliaryData as Record<string, unknown> | undefined;
return typeof aux?.group === 'string' ? aux.group : undefined;
}
/**
* Build a flat list of selectable items in DOM order from search results.
* When groups are present, items are ordered by group (preserving insertion order),
* with ungrouped items at the end — matching the DefaultRenderer layout.
*/
function buildSelectableItems(items: SearchableItem[]): SelectorOptionData[] {
const hasGroups = items.some(item => getGroup(item) != null);
if (!hasGroups) {
return items.map(item => ({
value: item.id,
label: item.label,
}));
}
// Group items preserving insertion order of groups
const groupOrder: string[] = [];
const groups = new Map<string, SearchableItem[]>();
const ungrouped: SearchableItem[] = [];
for (const item of items) {
const group = getGroup(item);
if (group != null) {
if (!groups.has(group)) {
groupOrder.push(group);
groups.set(group, []);
}
groups.get(group)?.push(item);
} else {
ungrouped.push(item);
}
}
const result: SelectorOptionData[] = [];
for (const heading of groupOrder) {
for (const item of groups.get(heading) ?? []) {
result.push({value: item.id, label: item.label});
}
}
for (const item of ungrouped) {
result.push({value: item.id, label: item.label});
}
return result;
}
/**
* O(1) value → index lookup over selectable items, used by the delegated
* mouseover handler (#6077). The index is built once per results change;
* each hover then pays a Map probe instead of a linear findIndex scan,
* so cost no longer scales with list size. Keeps the first occurrence of
* duplicate values to match the previous findIndex behavior.
*/
function createValueLookup<T extends {value: string}>(
items: ReadonlyArray<T>,
): (value: string) => number | undefined {
const indexByValue = new Map<string, number>();
for (let i = 0; i < items.length; i++) {
const value = items[i].value;
if (!indexByValue.has(value)) {
indexByValue.set(value, i);
}
}
return value => indexByValue.get(value);
}
interface RendererProps<T extends SearchableItem> {
items: T[];
value: string;
renderItem?: (item: T, isSelected: boolean) => ReactNode;
}
/**
* Renders items with optional per-item customization.
* Auto-groups by auxiliaryData.group when present.
* Passes `isSelected` so renderItem can handle picker-mode visuals.
*/
function ItemRenderer<T extends SearchableItem>({
items,
value,
renderItem,
}: RendererProps<T>) {
const renderOne = (item: T) => (
<CommandPaletteItem key={item.id} value={item.id}>
{renderItem ? renderItem(item, item.id === value) : item.label}
</CommandPaletteItem>
);
const hasGroups = items.some(item => getGroup(item) != null);
if (!hasGroups) {
return <>{items.map(renderOne)}</>;
}
const groupOrder: string[] = [];
const groups = new Map<string, T[]>();
const ungrouped: T[] = [];
for (const item of items) {
const group = getGroup(item);
if (group != null) {
if (!groups.has(group)) {
groupOrder.push(group);
groups.set(group, []);
}
groups.get(group)?.push(item);
} else {
ungrouped.push(item);
}
}
return (
<>
{groupOrder.map(heading => (
<CommandPaletteGroup key={heading} heading={heading}>
{(groups.get(heading) ?? []).map(renderOne)}
</CommandPaletteGroup>
))}
{ungrouped.map(renderOne)}
</>
);
}
/**
* Command palette root component.
*
* Uses `searchSource` for all search logic — same interface as Typeahead.
* For static lists, use `createStaticSource` from `@astryxdesign/core/Typeahead`.
*
* Keyboard navigation is handled by `useCombobox` from Selector for arrows,
* PageUp/PageDown, and Enter. Home/End remain native caret keys. Modal Escape
* dismissal delegates to Dialog's shared layer stack so nested surfaces handle
* the first press.
*
* Input and footer are rendered by default — only pass them to replace the defaults.
*
* @compositionHint
* - `input` slot: CommandPaletteInput (default)
* - `footer` slot: CommandPaletteFooter (default)
* - `renderItem(item, isSelected)`: custom per-item content (grouping preserved)
*
* @example
* ```
* <CommandPalette
* isOpen={isOpen}
* onOpenChange={setIsOpen}
* searchSource={createStaticSource(commands)}
* />
* ```
*/
export function CommandPalette<T extends SearchableItem = SearchableItem>({
ref,
isOpen,
isInline,
onOpenChange,
searchSource,
input,
footer,
renderItem,
emptySearchText: emptySearchTextFromProps,
emptyBootstrapText: emptyBootstrapTextFromProps,
value: controlledValue,
onValueChange,
label: labelFromProps,
width = 640,
maxHeight = 480,
...rest
}: CommandPaletteProps<T>) {
const t = useComponentTranslator();
const label = labelFromProps ?? t('@astryx.commandPalette.label');
const emptySearchText =
emptySearchTextFromProps ?? t('@astryx.commandPalette.emptySearch');
const emptyBootstrapText =
emptyBootstrapTextFromProps ?? t('@astryx.commandPalette.emptyBootstrap');
const listId = useId();
// search: the committed query — only advances when async results arrive.
// optimisticSearch: updates immediately on keystroke, drives input + empty state.
// This way optimisticSearch is always what the user sees, and search is what
// the current results actually correspond to.
const [search, setSearch] = useState('');
const [internalValue, setInternalValue] = useState('');
const [searchResults, setSearchResults] = useState<T[]>([]);
const [isPending, startTransition] = useTransition();
const [optimisticSearch, setOptimisticSearch] = useOptimistic(search);
const [optimisticResults, setOptimisticResults] =
useOptimistic(searchResults);
const isBusy = isPending;
const searchVersionRef = useRef(0);
const emptyStateRef = useRef<HTMLDivElement>(null);
const settleBusyAnnouncementRef = useRef<(() => void) | null>(null);
const registerBusyAnnouncementSettle = useCallback(
(settle: (() => void) | null) => {
settleBusyAnnouncementRef.current = settle;
},
[],
);
// Announce search results to screen readers through the shared polite live
// region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
// The empty states are otherwise purely visual, so a screen-reader user
// typing a query would hear nothing when results disappear. The busy start
// is announced by CommandPaletteInput.
const announce = useAnnounce();
const value = controlledValue ?? internalValue;
const setValue = useCallback(
(newValue: string) => {
if (controlledValue === undefined) {
setInternalValue(newValue);
}
onValueChange?.(newValue);
},
[controlledValue, onValueChange],
);
// Build flat selectable items in DOM order from search results.
// Must match the render order of ItemRenderer.
const selectableItems = useMemo(
() => buildSelectableItems(optimisticResults),
[optimisticResults],
);
const valueLookup = useMemo(
() => createValueLookup(selectableItems),
[selectableItems],
);
const handleClose = useCallback(() => {
// Invalidate any in-flight search. Most sources don't implement cancel(),
// and a response that resolves after close would still pass runSearch's
// version check and re-commit the stale query/results into the closed
// palette (visible as a ghost query on reopen while bootstrap is pending).
searchVersionRef.current++;
// Reset both committed and optimistic search on close
setSearch('');
setSearchResults([]);
if (controlledValue === undefined) {
setInternalValue('');
}
searchSource.cancel?.();
// Clear any lingering result / loading announcement when the palette
// closes so stale status text does not linger in the a11y tree
// (matching Selector's onHide).
announce('');
onOpenChange(false);
}, [onOpenChange, searchSource, controlledValue, announce]);
const selectItem = useCallback(
(itemValue: string) => {
setValue(itemValue);
},
[setValue],
);
// useCombobox handles all keyboard navigation and highlight state.
// We treat the palette as always "open" from the combobox's perspective
// (since the dialog itself handles open/close), and use onClose as a no-op
// for the combobox — the palette's own close is handled by handleClose.
const combobox = useCombobox({
selectableItems,
value,
isOpen: true, // Always "open" from combobox POV — the dialog handles visibility
onOpen: () => {}, // Dialog handles open
onClose: () => {}, // We handle close via handleClose
onSelect: (itemValue: string) => {
selectItem(itemValue);
handleClose();
},
listboxId: listId,
});
// Run a search for the given query and commit results.
// Called directly when the user types — no effect needed.
const runSearch = useCallback(
(query: string) => {
searchSource.cancel?.();
const version = ++searchVersionRef.current;
// A highlight belongs to the query that created it. Clear it before any
// optimistic narrowing so aria-activedescendant never shifts to a
// different command at the same index while the next result set loads.
combobox.setHighlightedIndex(-1);
startTransition(async () => {
const isBootstrap = query === '';
// The busy start ("Loading") is announced by CommandPaletteInput,
// from a region inside the palette's dialog (spec:AST-086 FR8, FR3).
// Client-filter previous results for instant narrowing while fetch is in flight
if (!isBootstrap && searchResults.length > 0) {
const lower = query.toLowerCase().trim();
setOptimisticResults(
searchResults.filter(item =>
item.label.toLowerCase().includes(lower),
),
);
}
let items: T[] = [];
try {
const result = isBootstrap
? searchSource.bootstrap()
: searchSource.search(query);
items = await Promise.resolve(result);
} catch {
// A failed request settles as an empty answer. React sends an
// uncaught error from this transition to the nearest error boundary.
}
if (searchVersionRef.current === version) {
if (!isBootstrap) {
// This query's outcome is announced below (a count) or from the
// rendered empty state; a busy start not yet announced would
// follow it, so the input drops it (spec:AST-086 FR8).
settleBusyAnnouncementRef.current?.();
}
// Commit query and results together
setSearch(query);
setOptimisticResults(items);
setSearchResults(items);
// Announce the outcome from the search commit (not a reactive
// effect), matching Selector / BaseTypeahead: exactly one
// announcement per committed non-empty query. Empty results are
// announced from their rendered content below so a caller-supplied
// ReactNode reaches assistive technology as written.
if (isBootstrap) {
announce('');
} else if (items.length > 0) {
announce(
t('@astryx.commandPalette.resultCount', {count: items.length}),
);
}
// When opening with a preselected value, highlight it once
// bootstrap results arrive. No value → highlight stays at -1
// and ArrowDown naturally moves to the first item. Inline previews
// take the hover-aware path so the initial highlight does not
// scrollIntoView the surrounding page (#6077).
if (isBootstrap && value != null && value !== '') {
const selectedIdx = items.findIndex(item => item.id === value);
if (selectedIdx >= 0) {
if (isInline) {
// `items` is the fresh bootstrap result; the closure's
// selectableItems may still be empty at commit time.
const selectedItem = items[selectedIdx];
if (selectedItem) {
combobox.onItemMouseEnter(
{value: selectedItem.id},
selectedIdx,
);
}
} else {
combobox.setHighlightedIndex(selectedIdx);
}
}
}
}
});
},
[
searchSource,
searchResults,
startTransition,
value,
isInline,
combobox,
setOptimisticResults,
announce,
t,
],
);
// Bootstrap on open. We use a ref to avoid re-triggering when
// runSearch's identity changes (it depends on searchResults).
const runSearchRef = useRef(runSearch);
runSearchRef.current = runSearch;
// Syncs the search source with `isOpen`. An open runs the empty-query search.
useEffect(() => {
if (isOpen) {
runSearchRef.current('');
}
}, [isOpen]);
// Wrap combobox's onKeyDown to preserve inline-preview Escape handling and
// select + close on Enter. Modal Escape stays unclaimed here so Dialog's
// shared dismissal stack can route it to the topmost surface.
const handleKeyDown = useCallback(
(e: React.KeyboardEvent) => {
if (e.key === 'Escape') {
// Modal CommandPalette delegates Escape to Dialog's shared dismissal
// stack so a nested layer handles the first press. Inline previews do
// not join that stack, so preserve their local close behavior.
if (isInline) {
e.preventDefault();
handleClose();
}
return;
}
if (e.key === 'Enter') {
e.preventDefault();
if (
combobox.highlightedIndex >= 0 &&
combobox.highlightedIndex < selectableItems.length
) {
const item = selectableItems[combobox.highlightedIndex];
if (item && !item.disabled) {
selectItem(item.value);
handleClose();
}
}
return;
}
// Home and End remain native caret-movement keys for this editable
// combobox. PageUp/PageDown provide first/last result navigation.
if (e.key === 'Home' || e.key === 'End') {
return;
}
// Space should type in the input, not trigger selection
if (e.key === ' ') {
return;
}
combobox.onKeyDown(e);
},
[combobox, handleClose, isInline, selectableItems, selectItem],
);
// Hover highlight is owned here by a single delegated handler on the list
// container: it routes to useCombobox's hover-aware path, which moves the
// highlight without scrolling (#6077) — a stationary pointer cannot
// re-highlight and auto-scroll in a runaway loop. Keeping it off the public
// context preserves CommandPaletteContextValue's setHighlightedIndex shape;
// disabled items are skipped via aria-disabled (selectableItems carries no
// disabled info). Use mouseover so moves between options bubble to the list;
// mouseenter only runs when the pointer enters the list from outside.
const handleListMouseOver = useCallback(
(e: React.MouseEvent) => {
const option = (e.target as HTMLElement).closest?.('[role="option"]');
if (!option || option.getAttribute('aria-disabled') === 'true') {
return;
}
const itemValue = option.getAttribute('data-value');
if (itemValue == null) {
return;
}
const index = valueLookup(itemValue);
if (index !== undefined) {
combobox.onItemMouseEnter(selectableItems[index], index);
}
},
[combobox, selectableItems, valueLookup],
);
const contextValue = useMemo(
() => ({
// Input uses optimisticSearch — reflects keystrokes immediately.
// setSearch calls setOptimisticSearch inside a transition for instant
// feedback then triggers the async search directly (no effect indirection).
search: optimisticSearch,
setSearch: (query: string) => {
startTransition(() => {
setOptimisticSearch(query);
});
runSearch(query);
},
value,
setValue,
listId,
highlightedIndex: combobox.highlightedIndex,
setHighlightedIndex: combobox.setHighlightedIndex,
getItemId: combobox.getItemId,
selectableItems,
searchResults: optimisticResults,
selectItem,
onKeyDown: handleKeyDown,
onClose: handleClose,
isOpen,
isBusy,
}),
[
optimisticSearch,
setOptimisticSearch,
runSearch,
value,
setValue,
listId,
combobox.highlightedIndex,
combobox.setHighlightedIndex,
combobox.getItemId,
selectableItems,
optimisticResults,
selectItem,
handleKeyDown,
handleClose,
isOpen,
isBusy,
],
);
// "No query" is the field's current value (`optimisticSearch`), so the
// bootstrap text never shows over a query the person has typed
// (component:CommandPaletteEmpty FR2). The search-empty text belongs to a
// committed query (`search`, which still holds the previous query while a
// transition is pending): it stays mounted across keystrokes after a query
// settled empty, so it never flashes. While the first query is pending and
// nothing is committed, neither text shows: the result surface keeps the
// Empty container's size with no message, so the dialog does not jump, and
// the Input's Loading spinner is the indicator (component:CommandPalette
// FR1 and its Pending search state row).
const hasQuery = optimisticSearch !== '';
const showEmptyBootstrap = !hasQuery && optimisticResults.length === 0;
const showEmptySearch =
hasQuery && search !== '' && optimisticResults.length === 0;
// Announce only once the search settles: while it is pending, optimistic
// narrowing can empty the list before the source answers, which would
// speak "No results" early or wrongly.
useAnnounceRenderedText(emptyStateRef, showEmptySearch && !isPending, search);
let listContent: ReactNode;
if (showEmptyBootstrap) {
listContent = (
<CommandPaletteEmpty ref={emptyStateRef}>
{emptyBootstrapText}
</CommandPaletteEmpty>
);
} else if (showEmptySearch) {
listContent = (
<CommandPaletteEmpty ref={emptyStateRef}>
{emptySearchText}
</CommandPaletteEmpty>
);
} else if (optimisticResults.length === 0) {
// A no-break space gives the empty container one line of height; it is
// hidden from assistive technology, which hears the busy start instead.
listContent = (
<CommandPaletteEmpty aria-hidden="true">{'\u00a0'}</CommandPaletteEmpty>
);
} else {
listContent = (
<ItemRenderer
items={optimisticResults}
value={value}
renderItem={renderItem}
/>
);
}
return (
<Dialog
ref={ref}
isOpen={isOpen}
isInline={isInline}
onOpenChange={open => {
if (!open) {
handleClose();
} else {
onOpenChange(true);
}
}}
width={width}
maxHeight={maxHeight}
purpose="info"
aria-label={label}
{...rest}>
<CommandPaletteContext value={contextValue}>
<Layout
defaultHasDividers
header={
<LayoutHeader hasDivider padding={0}>
<BusyStartSettleContext value={registerBusyAnnouncementSettle}>
{input ?? <CommandPaletteInput />}
</BusyStartSettleContext>
</LayoutHeader>
}
content={
<LayoutContent padding={0}>
<CommandPaletteList onMouseOver={handleListMouseOver}>
{listContent}
</CommandPaletteList>
</LayoutContent>
}
footer={
<LayoutFooter hasDivider padding={0}>
{footer ?? <CommandPaletteFooter />}
</LayoutFooter>
}
/>
</CommandPaletteContext>
</Dialog>
);
}
CommandPalette.displayName = 'CommandPalette';