CommandUpdated

Import

import { Command } from '@darkcode-ui/react';

Anatomy

Import the Command component and access all parts using dot notation. Command is the root provider — it wires up the overlay trigger, so place a trigger element (e.g. a Button) and the Command.Backdrop inside it.

<Command>
  <Command.Backdrop>
    <Command.Container>
      <Command.Dialog>
        <Command.Header />
        <Command.InputGroup>
          <Command.InputGroup.Prefix />
          <Command.InputGroup.Input />
          <Command.InputGroup.ClearButton />
          <Command.InputGroup.Suffix />
        </Command.InputGroup>
        <Command.List>
          <Command.Group>
            <Command.Item />
          </Command.Group>
          <Command.Separator />
        </Command.List>
        <Command.Footer />
      </Command.Dialog>
    </Command.Container>
  </Command.Backdrop>
</Command>

Usage

The palette opens from a trigger and filters its items as you type. Command.Dialog wraps an internal React Aria Autocomplete, so arrow keys move focus through the filtered list and Enter activates the focused item. Give each Command.Item a textValue so it can be matched while searching.

"use client";

import {Button, Command, Kbd, useOverlayState} from "@darkcode-ui/react";
import {CreditCard, FolderOpen, Magnifier, Person, Sparkles, SquarePlus} from "@gravity-ui/icons";
import {useEffect} from "react";

Opening with a shortcut

Drive the palette with useOverlayState and pass it to Command via the state prop to bind a global shortcut such as ⌘K. Call state.close() from Command.List's onAction to dismiss the palette after a selection.

import {Button, Command, useOverlayState} from '@darkcode-ui/react';
import {useEffect} from 'react';

function CommandMenu() {
  const state = useOverlayState();

  useEffect(() => {
    const onKeyDown = (event: KeyboardEvent) => {
      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
        event.preventDefault();
        state.toggle();
      }
    };

    window.addEventListener('keydown', onKeyDown);

    return () => window.removeEventListener('keydown', onKeyDown);
  }, [state]);

  return (
    <Command state={state}>
      <Button variant="secondary">Open</Button>
      <Command.Backdrop>
        <Command.Container>
          <Command.Dialog>
            <Command.InputGroup>
              <Command.InputGroup.Prefix />
              <Command.InputGroup.Input />
              <Command.InputGroup.ClearButton />
            </Command.InputGroup>
            <Command.List onAction={() => state.close()}>
              <Command.Item textValue="Profile">Profile</Command.Item>
            </Command.List>
          </Command.Dialog>
        </Command.Container>
      </Command.Backdrop>
    </Command>
  );
}

Clean

A pared-back palette with a single flat list and no header or footer.

"use client";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";

export function CommandClean() {

Dev Toolbar

Add a Command.Header above the input to host a title, breadcrumbs, or tabs.

"use client";

import {Button, Chip, Command, Kbd, useOverlayState} from "@darkcode-ui/react";
import {ArrowUturnCwRight, CircleDashed, CircleInfo, Gear, TrashBin} from "@gravity-ui/icons";

Launcher

An application launcher grouping recent items and apps inside a larger dialog.

"use client";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";
import {Bell, Calendar, Envelope, Globe, HardDrive, SquareArticle} from "@gravity-ui/icons";

Minimal

Just an input and a list — omit the prefix, clear button, groups, and footer.

"use client";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";

export function CommandMinimal() {

Split View

Combine a Command.Header with switchable lists to scope results to a category.

"use client";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";
import {Bookmark, Envelope, Gear, House, Person, SquarePlus} from "@gravity-ui/icons";
import {useState} from "react";

Multiple Search Terms

Pass a custom filter to Command.Dialog to match every whitespace-separated term independently, so dark settings matches Toggle Dark Mode Settings.

"use client";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";
import {ArrowUpFromLine, Person, Persons, Sparkles} from "@gravity-ui/icons";
import {useCallback} from "react";

Sizes

Set size on Command.Container to sm, md (default), or lg.

"use client";

import type {CommandContainerProps} from "@darkcode-ui/react";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";

Backdrop Variants

Set variant on Command.Backdrop to opaque (default), blur, or transparent.

"use client";

import type {CommandBackdropProps} from "@darkcode-ui/react";

import {Button, Command, useOverlayState} from "@darkcode-ui/react";

Styling

Passing Tailwind CSS classes

import {Command} from '@darkcode-ui/react';

<Command.Dialog className="max-w-2xl">
  {/* ... */}
</Command.Dialog>

Customizing the component classes

To customize the Command component classes, you can use the @layer components directive.
Learn more.

@layer components {
  .command__dialog {
    @apply rounded-3xl;
  }

  .command__item {
    @apply rounded-lg;
  }

  .command__group-heading {
    @apply uppercase tracking-wide;
  }
}

DarkCode UI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Command component uses these CSS classes (View source styles):

Base & Variant Classes

• .command__backdrop — Fixed fullscreen overlay behind the palette, with enter/exit animations.
• .command__backdrop--transparent — Fully transparent backdrop.
• .command__backdrop--opaque — Dark semi-transparent backdrop.
• .command__backdrop--blur — Dark backdrop with backdrop-blur-md.

Size Modifier Classes

• .command__dialog--sm — Small dialog (max-w-sm, max-height 300px).
• .command__dialog--md — Medium dialog (max-w-lg, max-height 356px). Default.
• .command__dialog--lg — Large dialog (max-w-xl, max-height 440px).

Element Classes

• .command__container — Positioning wrapper that centers the dialog near the top of the viewport with slide + zoom animations.
• .command__dialog — The command palette box (bg-overlay, shadow-overlay).
• .command__header — Content area above the input.
• .command__input-group — Search field row holding prefix, input, and suffix.
• .command__input-group-prefix — Leading content (e.g. a search icon).
• .command__input-group-input — The text input.
• .command__input-group-suffix — Trailing content.
• .command__input-group-clear-button — Clear button; hidden while the input is empty.
• .command__list — Scrollable command list (overflow-y-auto, overscroll-contain).
• .command__group — Section grouping items.
• .command__group-heading — Section label.
• .command__item — Individual command entry.
• .command__separator — Horizontal divider between groups.
• .command__footer — Bottom bar with hints.
• .command__empty — Empty state shown when no results match.

Interactive States

• [data-entering] / [data-exiting] on .command__backdrop and .command__container — enter/exit animations.
• [data-hovered] / [data-focused] on .command__item — applies bg-default.
• [data-pressed] on .command__item — applies bg-default-hover.
• [data-disabled] on .command__item — reduced opacity, default cursor.
• [data-empty] on .command__input-group — hides the clear button.
• motion-reduce:animate-none on all animated elements.

API Reference

Command

The root provider. Sets up the component context and overlay trigger.

Also supports all React Aria DialogTrigger props.

Command.Backdrop

The fullscreen overlay. Must wrap Command.Container.

Also supports all React Aria ModalOverlay props.

Command.Container

Positioning wrapper that centers the dialog. Must be placed inside Command.Backdrop.

Also supports all React Aria Modal props.

Command.Dialog

The command palette box. Wraps an internal Autocomplete for filtering.

Also supports all React Aria Dialog props.

Command.Header

Content area above the input (e.g. breadcrumbs or tabs). Renders a plain <div>.

Command.InputGroup

The search field container. Renders a React Aria SearchField.

Also supports all React Aria SearchField props.

Command.InputGroup.Prefix

Leading content inside the input group. Defaults to a search icon. Renders a plain <div>.

Command.InputGroup.Input

The text input element for searching commands.

Also supports all React Aria Input props.

Command.InputGroup.Suffix

Trailing content inside the input group. Renders a plain <div>.

Command.InputGroup.ClearButton

A button that clears the search input. Automatically hidden when the input is empty.

Also supports all CloseButton props.

Command.List

The scrollable list of command items. Backed by React Aria Menu.

Also supports all React Aria Menu props.

Command.Group

Groups related items under a heading.

Also supports all React Aria MenuSection props.

Command.Item

An individual command entry. Supports icons, labels, and trailing keyboard shortcuts.

Also supports all React Aria MenuItem props.

Command.Separator

A horizontal divider between groups. Renders a React Aria Separator.

Command.Footer

Content area below the list (e.g. keyboard shortcut hints). Renders a plain <div>.