Command

A dialog component that facilitates search functionality, often featuring fuzzy search capabilities for quick and efficient filtering.

Usage

A basic example to quickly demonstrate how the Command component works. This will showcase the essential functionality of the command interface in a simple, usable format.

"use client";
import { useState } from "react";
import { command, Command } from "@/ui/command";
import { HomeIcon } from "@/icons/*";
import { Button } from "@/ui/button";

const data = ["Home", "About us", "Contacts", "Blog", "Careers", "Terms of service"];

export function CommandDemo() {
  const [query, setQuery] = useState("");

  const items = data.filter(item => item.toLowerCase().includes(query.toLowerCase().trim())).map(item => <Command.Action key={item} label={item} />);

  return (
    <>
      <Button onClick={command.open}>Open Command</Button>

      <Command.Root query={query} onQueryChange={setQuery}>
        <Command.Search placeholder="Search..." leftSection={<HomeIcon stroke={1.5} />} />
        <Command.ActionsList>{items.length > 0 ? items : <Command.Empty>Nothing found...</Command.Empty>}</Command.ActionsList>
      </Command.Root>
    </>
  );
}

Interactive configurator to explore different customization options for the Command component. This section allows users to adjust properties such as state control, error handling, and other configurable aspects of the Command component.

Nothing found

Highlight query

Clear query on close

import { Command, type CommandActionGroupData } from "@/ui/command";
import { FolderSearchIcon } from "@/icons/*";
const dataGroup: CommandActionGroupData[] = [
  {
    group: "Frontend Frameworks",
    actions: [
      { id: "1-1", href: "https://reactjs.org/", label: "React", description: "A JavaScript library for building user interfaces." },
      { id: "1-2", href: "https://vuejs.org/", label: "Vue.js", description: "A progressive framework for building user interfaces." }
    ]
  },
  {
    group: "Backend Frameworks",
    actions: [
      { id: "2-1", href: "https://expressjs.com/", label: "Express", description: "Fast, unopinionated, minimalist web framework for Node.js." },
      { id: "2-2", href: "https://nestjs.com/", label: "NestJS", description: "A progressive Node.js framework for building efficient and scalable server-side applications." }
    ]
  },
  {
    group: "Databases",
    actions: [
      { id: "3-1", href: "https://www.mongodb.com/", label: "MongoDB", description: "A document database with the scalability and flexibility that you want with the querying and indexing that you need." },
      { id: "3-2", href: "https://www.postgresql.org/", label: "PostgreSQL", description: "A powerful, open-source object-relational database system." }
    ]
  },
  {
    group: "CSS Frameworks",
    actions: [
      { id: "4-1", href: "https://tailwindcss.com/", label: "Tailwind CSS", description: "A utility-first CSS framework for rapidly building custom user interfaces." },
      { id: "4-2", href: "https://getbootstrap.com/", label: "Bootstrap", description: "The most popular HTML, CSS, and JavaScript framework for developing responsive, mobile-first projects on the web." }
    ]
  },
  {
    group: "Development Tools",
    actions: [
      { id: "5-1", href: "https://code.visualstudio.com/", label: "VS Code", description: "A source-code editor developed by Microsoft for Windows, Linux, and macOS." },
      { id: "5-2", href: "https://git-scm.com/", label: "Git", description: "A free and open-source distributed version control system designed to handle everything from small to very large projects with speed and efficiency." }
    ]
  }
];
export function CommandDemo() {
  return (
    <Command
      highlightQuery={false}
      container={null}
      forceMount
      actions={dataGroup}
      searchProps={{ autoFocus: false, leftSection: <FolderSearchIcon stroke={1.5} /> }}
    />
  );
}

Data Types

Defines the structure of the data used by the Command component. The Command component can handle both static and dynamic data, depending on whether you choose to define data using props.actions or manually specifying the children components.

Important:
- Either props.actions or children should be specified; you cannot use both at the same time or omit both.
- Using both options simultaneously will cause confusion in the function and omitting both will result in no action being executed.
- To prevent this conflict, error handling is implemented to ensure that only one data type (either props.actions or children) is used.
Alternative Approach:
- You can use the <Command.Root> compound component to group multiple <Command> components together while managing their data types effectively.

Data Single

Demonstrates how to define a single data item for the Command component. Ideal for situations where you need to display a simple, single-action command with minimal configuration.

"use client";
import { Command, type CommandActionData } from "@/ui/command";
import { CommandIcon, CodeSquareIcon, HomeIcon } from "@/icons/*";

const singleData: CommandActionData[] = [
  { id: "1", href: "/", label: "Home", description: "Get to home page", leftSection: <HomeIcon size={18} /> },
  { id: "2", href: "/docs", label: "Docs", description: "Get to docs page", leftSection: <CommandIcon size={18} /> },
  { id: "3", href: "/docs/web/components", label: "Components", description: "Get to components page", leftSection: <CodeSquareIcon size={18} /> }
];

export function CommandDataTypesSingleDemo() {
  return <Command container={null} forceMount actions={singleData} nothingFound="Oops..." searchProps={{ autoFocus: false }} />;
}

Data Group

Shows how to define a group of data for the Command component. This allows multiple actions or commands to be grouped together, useful for when you want to provide several related options in a single command interface.

import { Command, type CommandActionGroupData } from "@/ui/command";

const dataGroup: CommandActionGroupData[] = [
  {
    group: "Frontend Frameworks",
    actions: [
      { id: "1-1", href: "https://reactjs.org/", label: "React", description: "A JavaScript library for building user interfaces." },
      { id: "1-2", href: "https://vuejs.org/", label: "Vue.js", description: "A progressive framework for building user interfaces." }
    ]
  },
  {
    group: "Backend Frameworks",
    actions: [
      { id: "2-1", href: "https://expressjs.com/", label: "Express", description: "Fast, unopinionated, minimalist web framework for Node.js." },
      { id: "2-2", href: "https://nestjs.com/", label: "NestJS", description: "A progressive Node.js framework for building efficient and scalable server-side applications." }
    ]
  },
  {
    group: "Databases",
    actions: [
      { id: "3-1", href: "https://www.mongodb.com/", label: "MongoDB", description: "A document database with the scalability and flexibility that you want with the querying and indexing that you need." },
      { id: "3-2", href: "https://www.postgresql.org/", label: "PostgreSQL", description: "A powerful, open-source object-relational database system." }
    ]
  },
  {
    group: "CSS Frameworks",
    actions: [
      { id: "4-1", href: "https://tailwindcss.com/", label: "Tailwind CSS", description: "A utility-first CSS framework for rapidly building custom user interfaces." },
      { id: "4-2", href: "https://getbootstrap.com/", label: "Bootstrap", description: "The most popular HTML, CSS, and JavaScript framework for developing responsive, mobile-first projects on the web." }
    ]
  },
  {
    group: "Development Tools",
    actions: [
      { id: "5-1", href: "https://code.visualstudio.com/", label: "VS Code", description: "A source-code editor developed by Microsoft for Windows, Linux, and macOS." },
      { id: "5-2", href: "https://git-scm.com/", label: "Git", description: "A free and open-source distributed version control system designed to handle everything from small to very large projects with speed and efficiency." }
    ]
  }
];

export function CommandDataTypesGroupDemo() {
  return <Command container={null} forceMount actions={dataGroup} nothingFound="Nothing..." searchProps={{ autoFocus: false }} />;
}

Multiple Command

When using the Command component in multiple places or contexts with different states, it’s essential to create separate store and storeState instances using the createCommand() function. This ensures that each command operates independently and does not interfere with others.

"use client";
import { Command, createCommand } from "@/ui/command";
import { Button } from "@/ui/button";
import { Stack } from "@/ui/stack";

const [firstStore, firstStoreState] = createCommand();
const [secondStore, secondStoreState] = createCommand();

export function CommandMultipleDemo() {
  return (
    <Stack>
      <Command store={firstStore} actions={[{ id: "command-1", label: "Command 1" }]} />
      <Command store={secondStore} actions={[{ id: "command-2", label: "Command 2" }]} />

      <Button onClick={firstStoreState.open}>Open Command 1</Button>
      <Button onClick={secondStoreState.open}>Open Command 2</Button>
    </Stack>
  );
}

API References

Styles API

type T =
  | "search"
  | "overlay"
  | "content"
  | "footer"
  | "searchWrap"
  | "searchLabel"
  | "closeCommand"
  | "empty"
  | "actionsOrder"
  | "actionSection"
  | "actionsList"
  | "actionsGroup"
  | "actionGroupLabel"
  | "action"
  | "actionLabel"
  | "actionInner"
  | "highlight"
  | "actionDescription"
  | "actionLeftSection"
  | "actionRightSection"
  | "footer";

Styles API	Type	Default	Annotation
unstyled`?`	`Partial<Record<T, boolean>>`	`false`	if `true`, default styles will be removed
className`?`	`string`	`undefined`	pass to root component `<div>`
classNames`?`	`Partial<Record<T, string>>`	`undefined`
style`?`	`CSSProperties`	`undefined`	pass to root component `<div>`
styles`?`	`Partial<Record<T, CSSProperties>>`	`undefined`

Props API

Props API	Type	Default	Annotation
container`?`	`Element \| DocumentFragment \| null`	`document.body`	Specify a container element to portal the content into.
forceMount`?`	`boolean`	`false`	Used to force mounting when more control is needed.

Source Codes

Full working code example, including necessary markup and styles. You can copy and paste this code directly to start using the component immediately.

command.tsx