# Command **Category**: react **URL**: https://ui.darkcode.dev/en/docs/react/components/command **Source**: https://raw.githubusercontent.com/DarkCode-Developers/darkcode-ui/refs/heads/main/apps/docs/content/docs/en/react/components/(navigation)/command.mdx > A command palette with fuzzy search, keyboard navigation, and grouped actions for quick access. *** ## Import ```tsx 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. ```tsx ``` ### 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. ```tsx "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"; export function CommandDefault() { 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 ( state.close()}> New File ⌘N New Folder ⌘⇧N Search Files ⌘P Profile ⌘, Appearance Billing ↑ ↓ to navigate ↵ to select esc to close ); } ``` ### Opening with a shortcut Drive the palette with [`useOverlayState`](/react/hooks/use-overlay-state) 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. ```tsx 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 ( state.close()}> Profile ); } ``` ### Clean A pared-back palette with a single flat list and no header or footer. ```tsx "use client"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; export function CommandClean() { const state = useOverlayState(); return ( state.close()}> Dashboard Projects Team Reports Settings ); } ``` ### Dev Toolbar Add a `Command.Header` above the input to host a title, breadcrumbs, or tabs. ```tsx "use client"; import {Button, Chip, Command, Kbd, useOverlayState} from "@darkcode-ui/react"; import {ArrowUturnCwRight, CircleDashed, CircleInfo, Gear, TrashBin} from "@gravity-ui/icons"; export function CommandDevToolbar() { const state = useOverlayState(); return ( Developer Tools state.close()}> Toggle Inspector beta Show Performance Overlay Clear Cache Rebuild Project ⌘B Restart Server ); } ``` ### Launcher An application launcher grouping recent items and apps inside a larger dialog. ```tsx "use client"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; import {Bell, Calendar, Envelope, Globe, HardDrive, SquareArticle} from "@gravity-ui/icons"; export function CommandLauncher() { const state = useOverlayState(); return ( state.close()}> Calendar Mail Notes Browser Files Reminders ); } ``` ### Minimal Just an input and a list — omit the prefix, clear button, groups, and footer. ```tsx "use client"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; export function CommandMinimal() { const state = useOverlayState(); return ( state.close()}> Copy Cut Paste Duplicate Delete ); } ``` ### Split View Combine a `Command.Header` with switchable lists to scope results to a category. ```tsx "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"; export function CommandSplitView() { const state = useOverlayState(); const [category, setCategory] = useState<"actions" | "navigation">("actions"); return (
{(["actions", "navigation"] as const).map((value) => ( ))}
{category === "actions" ? ( state.close()}> Create Issue Assign to me Add Label ) : ( state.close()}> Go to Dashboard Go to Inbox Go to Settings )} ); } ``` ### 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`. ```tsx "use client"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; import {ArrowUpFromLine, Person, Persons, Sparkles} from "@gravity-ui/icons"; import {useCallback} from "react"; export function CommandMultipleSearchTerms() { const state = useOverlayState(); // Matches when every whitespace-separated term is contained in the item text, // so "dark settings" matches "Toggle Dark Mode Settings". const filter = useCallback((textValue: string, inputValue: string) => { const haystack = textValue.toLowerCase(); return inputValue .toLowerCase() .split(/\s+/) .filter(Boolean) .every((term) => haystack.includes(term)); }, []); return ( state.close()}> Toggle Dark Mode Settings Open Account Settings Export Data as CSV Invite Team Member ); } ``` ### Sizes Set `size` on `Command.Container` to `sm`, `md` (default), or `lg`. ```tsx "use client"; import type {CommandContainerProps} from "@darkcode-ui/react"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; function SizedCommand({size}: {size: CommandContainerProps["size"]}) { const state = useOverlayState(); return ( state.close()}> Profile Billing Notifications Security ); } export function CommandSizes() { return (
); } ``` ### Backdrop Variants Set `variant` on `Command.Backdrop` to `opaque` (default), `blur`, or `transparent`. ```tsx "use client"; import type {CommandBackdropProps} from "@darkcode-ui/react"; import {Button, Command, useOverlayState} from "@darkcode-ui/react"; function BackdropCommand({variant}: {variant: CommandBackdropProps["variant"]}) { const state = useOverlayState(); return ( state.close()}> Home Explore Library ); } export function CommandBackdropVariants() { return (
); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {Command} from '@darkcode-ui/react'; {/* ... */} ``` ### Customizing the component classes To customize the Command component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .command__dialog { @apply rounded-3xl; } .command__item { @apply rounded-lg; } .command__group-heading { @apply uppercase tracking-wide; } } ``` DarkCode UI follows the [BEM](https://getbem.com/) 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](https://github.com/DarkCode-Developers/darkcode-ui/blob/main/packages/styles/components/command.css)): #### 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. | Prop | Type | Default | Description | |------|------|---------|-------------| | `state` | `UseOverlayStateReturn` | — | Controlled overlay state from `useOverlayState` (e.g. for ⌘K shortcuts). | | `children` | `ReactNode` | — | A trigger element and the `Command.Backdrop`. | Also supports all React Aria [DialogTrigger](https://react-spectrum.adobe.com/react-aria/Dialog.html) props. ### Command.Backdrop The fullscreen overlay. Must wrap `Command.Container`. | Prop | Type | Default | Description | |------|------|---------|-------------| | `variant` | `'opaque' \| 'blur' \| 'transparent'` | `'opaque'` | Backdrop visual style. | | `isDismissable` | `boolean` | `true` | Whether clicking the backdrop closes the palette. | Also supports all React Aria [ModalOverlay](https://react-spectrum.adobe.com/react-aria/Modal.html) props. ### Command.Container Positioning wrapper that centers the dialog. Must be placed inside `Command.Backdrop`. | Prop | Type | Default | Description | |------|------|---------|-------------| | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the command dialog. | Also supports all React Aria [Modal](https://react-spectrum.adobe.com/react-aria/Modal.html) props. ### Command.Dialog The command palette box. Wraps an internal `Autocomplete` for filtering. | Prop | Type | Default | Description | |------|------|---------|-------------| | `defaultInputValue` | `string` | — | Default search input value (uncontrolled). | | `inputValue` | `string` | — | Controlled search input value. | | `onInputChange` | `(value: string) => void` | — | Callback when the search input changes. | | `filter` | `(textValue: string, inputValue: string) => boolean` | Case-insensitive contains | Custom filter function. | Also supports all React Aria [Dialog](https://react-spectrum.adobe.com/react-aria/Dialog.html) props. ### Command.Header Content area above the input (e.g. breadcrumbs or tabs). Renders a plain `
`. ### Command.InputGroup The search field container. Renders a React Aria `SearchField`. | Prop | Type | Default | Description | |------|------|---------|-------------| | `autoFocus` | `boolean` | `true` | Whether the input is focused when the palette opens. | Also supports all React Aria [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) props. ### Command.InputGroup.Prefix Leading content inside the input group. Defaults to a search icon. Renders a plain `
`. ### Command.InputGroup.Input The text input element for searching commands. | Prop | Type | Default | Description | |------|------|---------|-------------| | `placeholder` | `string` | `'Search commands...'` | Placeholder text. | Also supports all React Aria [Input](https://react-spectrum.adobe.com/react-aria/TextField.html) props. ### Command.InputGroup.Suffix Trailing content inside the input group. Renders a plain `
`. ### Command.InputGroup.ClearButton A button that clears the search input. Automatically hidden when the input is empty. Also supports all [CloseButton](/react/components/close-button) props. ### Command.List The scrollable list of command items. Backed by React Aria `Menu`. | Prop | Type | Default | Description | |------|------|---------|-------------| | `renderEmptyState` | `() => ReactNode` | `No results found.` | Custom empty state content when no items match. | | `onAction` | `(key: Key) => void` | — | Called when an item is activated. | Also supports all React Aria [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html) props. ### Command.Group Groups related items under a heading. | Prop | Type | Default | Description | |------|------|---------|-------------| | `heading` | `ReactNode` | — | Heading label for the group. | Also supports all React Aria [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#sections) props. ### Command.Item An individual command entry. Supports icons, labels, and trailing keyboard shortcuts. | Prop | Type | Default | Description | |------|------|---------|-------------| | `textValue` | `string` | — | Text used for filtering and typeahead. | | `isDisabled` | `boolean` | `false` | Whether the item is disabled. | Also supports all React Aria [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#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 `
`.