CommandPalette

A full-featured command menu (Cmd+K / Ctrl+K) for quick navigation and actions. Supports search, keyboard navigation, sections, shortcuts, and is fully ARIA-compliant.

---

Usage

Basic usage

import { CommandPalette } from '@nofinite/nui';

<CommandPalette
  sections={[
    {
      title: 'Navigation',
      items: [
        { id: 'home', label: 'Home' },
        { id: 'profile', label: 'Profile' },
      ],
    },
  ]}
/>;

Open with Cmd + K (Mac) or Ctrl + K (Windows/Linux)

---

Variants

CommandPalette does not expose visual variants via props.

Customization approach:

• Use className for custom styling.
• Override CSS variables or component classes.

<CommandPalette className="my-command-palette" sections={...} />

---

Sizes

The component has a fixed default size optimized for command menus.

• Width: 520px
• Max height: 70vh

To customize layout, override styles:

.my-command-palette {
  width: 640px;
}

---

States

Open / Closed

• Closed by default

• Opens via:

  • Cmd + K (Mac)
  • Ctrl + K (Windows / Linux)

Active Item

• Highlighted via keyboard navigation or hover
• Loops automatically from last to first item

Empty State

When no results match the search:

No results

---

Native Props / Composition

CommandPalette renders inside a portal and behaves like a modal dialog.

<CommandPalette
  className="custom-palette"
  placeholder="Type a command…"
  sections={...}
/>

---

Props

CommandPalette

Prop	Type	Default	Description
sections	CommandSection[]	—	Sections and command items to display
placeholder	string	"Search commands…"	Placeholder text for search input
className	string	""	Custom class for styling the container

---

CommandSection

Prop	Type	Description
title	string	Optional section heading
items	CommandItem[]	List of command items in the section

---

CommandItem

Prop	Type	Description
id	string	Unique identifier
label	string	Primary command label
icon	ReactNode	Optional leading icon
shortcut	string	Keyboard shortcut hint (visual only)
description	string	Secondary description text
onSelect	() => void	Callback executed when item is selected

---

Behavior Notes

• Search filtering is case-insensitive and matches against label.

• Keyboard navigation:

  • ↑ / ↓ to navigate items
  • Enter to select
  • Esc to close

• Navigation loops across all sections.

• Clicking outside closes the palette.

• Selecting an item automatically closes the palette.

Example:

{
  id: "settings",
  label: "Settings",
  shortcut: "⌘,",
  onSelect: () => openSettings(),
}

---

Accessibility

• Renders as: <div role="dialog" aria-modal="true">

• Fully keyboard navigable

• Search input is auto-focused on open

• Supports screen readers via semantic roles

• Recommendations:

  • Provide clear labels
  • Avoid icon-only commands without text

---

Layout

• Fixed, centered modal
• Uses a full-screen overlay
• Scrollable command list
• Content constrained to viewport height

<CommandPalette
  className="w-full max-w-xl"
  sections={...}
/>

---

Best Practices

Do

• Group commands logically using sections
• Provide clear, concise labels
• Add shortcuts for frequently used actions
• Close the palette after command execution

Don’t

• Overload a single section with too many items
• Use it as a replacement for full navigation UI
• Trigger destructive actions without confirmation
• Rely on shortcut text alone for meaning