CommandPalette

CommandPalette is an overlay that gives users fast access to actions, records, and content from anywhere in Brevo. Typically opened with a keyboard shortcut, it combines global search with command execution in a single interface.

Status: Content below is sourced from the Naos Figma documentation page for CommandPalette (file nfTKjsYTKM2qvIo8KXDAXV, node 7934:1233, "🧩 Naos – Forms and inputs", checked 2026-08-19) plus the component's TypeScript source. This page has real, detailed prose (Overview, Anatomy, Placement, Behavior, Keyboard Shortcuts, Accessibility) — unlike several other pages in this file. Nothing below is invented.

Source: DTSL/design-system → packages/product/organisms/commandPalette/src/CommandPalette.tsx (package @dtsl/naos-command-palette, exported as CommandPalette)

Props (verbatim from source, including its real inline JSDoc comments)

interface CommandPaletteProps {
	/**
	 * Handle from {@link useCommandPalette}. Owns visibility, the input
	 * ref, and stable DOM ids — call its `open` / `close` / `toggle`
	 * methods from your trigger UI.
	 */
	palette: CommandPaletteHandle
	query: string
	onQueryChange: (query: string) => void
	isLoading?: boolean
	results?: SearchCategory[]
	totalCount?: number
	maxItemsPerCategory?: number
	labels?: CommandPaletteLabels
	emptyState?: EmptyStateConfig
	onItemClick: (item: SearchResultItem) => void
	onSeeAllResults: (query: string) => void
	onAdvancedSearch: () => void
	/**
	 * Whether this palette should bind the global Cmd/Ctrl+K toggle.
	 * If two palettes ever mount at once (Storybook side-by-side, app-shell
	 * + nested feature) only one should listen — set this to `false` on the
	 * others to avoid pressing Cmd+K opening every palette at once.
	 *
	 * @default true
	 */
	registerGlobalShortcut?: boolean
}

Anatomy

CommandPalette (top level): 1. SearchBar, 2. Advanced search, 3. Number of results, 4. Content, 5. See all results, 6. ScrollBar

CommandPaletteContent (the .CommandPaletteContent sub-component): 1. Title, 2. CommandPaletteItem (repeated per result)

CommandPaletteItem: 1. Item name, 2. Details — optional, 3. Keyboard shortcut — optional

When to Use / Real Behavior

Real, from the Figma "Behavior" section:

Opening and closing. CommandPalette opens and closes with the same keyboard shortcut (⌘K). Users can also close it by using ESC or clicking outside the CommandPalette.

Results, Actions and Keyboard Shortcuts. When the CommandPalette first opens, it displays the user's five most recently accessed records and apps. As the user types, results match on intent rather than exact strings. Fuzzy matching accounts for typos and keyword associations, so a query like "make" can surface create-related actions even if the word "make" does not appear in the action name. Additionally, the CommandPalette should suggest actions even when there are no matching search results — for example, if the user types "Andrea" and no search results match, in addition to an empty state, CommandPalette should also suggest "Create new contact 'Andrea'".

Placement

Real, from the Figma "Placement" section:

CommandPalette appears centered on the screen, overlaying all other content without being tied to any specific UI element. When the viewport width shrinks, CommandPalette maintains its size by reducing margins down to a minimum of 40px or less. If the viewport continues to narrow, CommandPalette will shrink to a minimum width of 320px before switching to the mobile version.

CRITICAL: Keyboard shortcut design rules (verbatim from Figma)

The CommandPalette should be triggered by a single, simple shortcut. When defining or confirming the shortcut, avoid:

• Shortcuts that conflict with OS or browser conventions (e.g. Cmd+P)
• Alt + alphanumeric combinations (may conflict with access keys)
• Characters that vary across keyboard layouts: @ $ {} [] \ ~ | ^ ' < >
• Three-key combinations or keys that are far apart
• Ctrl+Alt combinations (interpreted as AltGR on some Windows locales)
• Adding a modifier to an existing shortcut for an unrelated action

Only repurpose a standard shortcut if the original action has no relevance in the app.

Real shortcut table, verbatim:

Action	Shortcut
Trigger CommandPalette	Cmd/Ctrl + K
Create contact	Cmd/Ctrl + Shift + C
Create campaign	Cmd/Ctrl + Shift + M
Create automation	Cmd/Ctrl + Shift + A
Import contacts	Cmd/Ctrl + Shift + I
Create deal	Cmd/Ctrl + Shift + D
Draft new email	Cmd/Ctrl + Shift + E

Also, per source: only one mounted CommandPalette instance should have registerGlobalShortcut enabled (default true) at a time, or Cmd/Ctrl+K opens every instance simultaneously.

Accessibility

Real, verbatim from the Figma "Accessibility" section:

The CommandPalette opens from anywhere via Cmd/Ctrl + K, immediately focusing the search input, and is fully operable by keyboard from there: arrow keys navigate results, Enter selects the highlighted item, and Tab cycles through the palette's interactive elements — search input, clear-input button (when filled), advanced search button, and "see all results" CTA.

This is backed by full ARIA support: the overlay is a role="dialog" with aria-modal="true" and a descriptive aria-label; the search field is a role="combobox" with aria-expanded, aria-controls, and aria-autocomplete="list", updating aria-activedescendant as users arrow through results so screen readers announce each selection in place; and the results form a role="listbox" of role="option" items with aria-selected state.

Dynamic feedback like result count and loading status is announced via aria-live="polite" regions, and focus is managed throughout — auto-focused on open, trapped within the overlay (via BaseOverlay), and restored to the previously active element on close.

Confirms a real dependency: CommandPalette's focus trap is built on base-overlay.

Common Mistakes

• ❌ Mounting multiple CommandPalette instances without setting registerGlobalShortcut={false} on all but one
• ❌ Assigning a custom keyboard shortcut that conflicts with OS/browser conventions or varies across keyboard layouts (see the CRITICAL rules above)
• ❌ Showing only an empty state with no results — CommandPalette should still suggest a relevant create-action when search finds nothing