CommandPalette

Usage

import { CommandPalette } from "@devvy-ui/react";

<CommandPalette title="Quick actions" open={open} onOpenChange={setOpen} items={commands} />

API reference

Native HTML attributes, className, style and a forwarded ref are supported. Component-specific props:

Prop	Type	Default	Description
items	CommandItem[]	required	Unique ids, labels, optional descriptions/disabled and callbacks.
Dialog props	DialogProps	required	Title, visibility, focus and dismissal.
placeholder	string	Search commands…	Search hint.

Source ownership

Run npx @devvy-ui/cli init once in your React project, then add the source:

npx @devvy-ui/cli add command-palette

Make the source yours.

Start from the canonical implementation used by the package and registry. Change the code, keep the MIT notice, and build the behavior your project needs.

CommandPalette.tsxREACT / TSX

import { forwardRef, useEffect, useId, useRef, useState } from 'react';
import { Dialog, type DialogProps } from './Dialog';
export interface CommandItem {
  id: string;
  label: string;
  description?: string;
  disabled?: boolean;
  onSelect: () => void;
}
export interface CommandPaletteProps extends Omit<DialogProps, 'children'> {
  items: readonly CommandItem[];
  placeholder?: string;
}
export const CommandPalette = forwardRef<HTMLDialogElement, CommandPaletteProps>(
  function CommandPalette({ items, placeholder = 'Search commands…', ...props }, ref) {
    const [query, setQuery] = useState(''),
      [active, setActive] = useState(0),
      input = useRef<HTMLInputElement>(null),
      id = useId(),
      filtered = items.filter((item) =>
        item.label.toLocaleLowerCase().includes(query.toLocaleLowerCase()),
      );
    const enabled = filtered.flatMap((item, i) => (item.disabled ? [] : [i])),
      current = enabled.includes(active) ? active : enabled[0];
    useEffect(() => {
      if (!props.open) {
        setQuery('');
        setActive(0);
      }
    }, [props.open]);
    return (
      <Dialog
        {...props}
        ref={ref}
        initialFocusRef={input}
        className={['dvy-command-palette', props.className].filter(Boolean).join(' ')}
      >
        <input
          ref={input}
          className="dvy-input"
          aria-label="Search commands"
          placeholder={placeholder}
          role="combobox"
          aria-autocomplete="list"
          aria-expanded={props.open}
          aria-controls={id}
          aria-activedescendant={current === undefined ? undefined : id + '-' + current}
          value={query}
          onChange={(e) => {
            setQuery(e.target.value);
            setActive(0);
          }}
          onKeyDown={(event) => {
            if (event.nativeEvent.isComposing) return;
            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
              event.preventDefault();
              const at = enabled.indexOf(current);
              setActive(
                enabled[
                  (at + (event.key === 'ArrowDown' ? 1 : -1) + enabled.length) % enabled.length
                ] ?? 0,
              );
            } else if (event.key === 'Enter' && current !== undefined) {
              event.preventDefault();
              const action = filtered[current];
              if (action && !action.disabled) {
                props.onOpenChange(false);
                action.onSelect();
              }
            }
          }}
        />
        <div id={id} role="listbox" aria-label="Commands">
          {filtered.map((item, i) => (
            <div
              key={item.id}
              id={id + '-' + i}
              role="option"
              aria-selected={i === current}
              aria-disabled={item.disabled || undefined}
              className="dvy-command-option"
              onPointerDown={(e) => {
                e.preventDefault();
                if (!item.disabled) {
                  props.onOpenChange(false);
                  item.onSelect();
                }
              }}
            >
              <strong>{item.label}</strong>
              {item.description && <small>{item.description}</small>}
            </div>
          ))}
          {!filtered.length && <p role="status">No matching commands.</p>}
        </div>
      </Dialog>
    );
  },
);

Edit your own copy. Downloaded source uses your changes; the component preview above uses the shipped version. Run the source installer first to include shared helpers.

Interactive preview

Usage

API reference

Accessibility & behavior

Platform Behavior & Guidelines

Source ownership

Make the source yours.