--- title: "Command" slug: command category: component type: documentation version: 20.0.0 tokens: 1962 source: https://ovh.github.io/design-system/v20.0.0/llms/react-components-command--documentation.txt --- # Command _The **Command** component provides a fast and efficient way to search, filter, and trigger actions from anywhere in an application._ ## Overview The **Command** component is a modal-like overlay that allows users to quickly find and execute actions or navigate through the application. It accelerates workflows by centralizing shortcuts and actions into a single entry point. | | | |---|---| | Name | Command | | Also known as | Command Menu, Command Palette, Spotlight, Quick Actions | | Source | https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/command | ## Usage The **Command** component is ideal for applications with a rich set of actions, navigation entries, or shortcuts, where speed and discoverability are critical. It is commonly used for: - Productivity tools and dashboards - Developer tools and admin interfaces - Large applications with deep navigation The **Command** component acts as a generic container. It does not enforce how commands are visually rendered, allowing integrators full freedom to define the dropdown content structure. ### Dos & Don'ts **Do** - Use Command as a global entry point for actions and navigation - Group related commands to improve scanability - Keep command labels concise and action-oriented - Use icons and shortcut hints to help users quickly identify commands **Don't** - Don’t use Command for critical or destructive actions without confirmation - Don’t overload Command with too many unrelated actions, which can overwhelm users - Don’t rely solely on Command for essential navigation; it should complement, not replace, standard UI ### Best Practices in Context 1. **Command** 2. **Search input** 3. **Command container** 4. **Item** 5. **Group** - optional ## Placement The **Command** component opens as a centered, modal-like overlay on top of the application content. ## Behavior ### Opening & Closing The **Command** opens as an overlay centered in the viewport. It can be triggered: - Via a dedicated UI trigger - Via a keyboard shortcut (⌘ + K on macOS, Ctrl + K on Windows/Linux) The Command closes when: - The Escape key is pressed - The overlay is dismissed Selecting an item does not close the Command. To close it on selection, control the `open` state and set it to `false` from the option's `onSelect` callback (see the Controlled example on the Examples page). ### Search & Filtering - The Command provides a search input used to filter available items: by default, typing filters the options on their text content. - Passing a `value` to **CommandFilter** switches to controlled filtering: the built-in filtering is fully disabled. The integrator owns the query state (updated through `onChange`) and is responsible for rendering only the matching options. ### Items & Groups Items are displayed in a vertically scrollable list and can be organized into groups. Groups, dividers, headers, and any additional UI elements are fully customizable. Each item may expose: - Label (required) - Icon (optional) - Shortcut hint (optional, e.g. ⌘ + N) - Description (optional) - Custom content ### Custom Rendering Integrators are free to render: - Badges - Keyboard hints (kbd) - Icons - Group headers - Dividers - Any custom layout or component The Command component does not impose constraints on item layout or structure. ## Navigation ### Focus Management When the Command opens, focus is set on the search input. Focus stays on the search input while navigating: the arrow keys move a visual highlight through the items, exposed to assistive technology via `aria-activedescendant` (see the Roles section). Focus remains trapped within the Command until it is closed. ### General Keyboard Shortcuts Pressing `↓` or `↑` highlights the next / previous item. Pressing `Enter` executes the highlighted item. Pressing `Escape` closes the Command. Pressing `Home` or `End` moves the cursor within the search input. ## Accessibility ### Roles **Command** is a `listbox`-based component, nested within a `dialog` role element. The search input has a `combobox` role, and an `aria-controls` relationship with the `listbox` (**CommandList**). ```tsx --> role='dialog' --> role='combobox' --> role='listbox' --> role='group' --> role='option' ``` ### Labelling - Because the **Command** dialog does not display a visible title by default, you must supply an accessible name for it. Use the `aria-label` prop on **CommandContent** to give screen readers a meaningful description of the dialog when it opens. - The **CommandFilter** search input does not render a visible label, so you must provide an accessible name for it. - A `listbox` must always have an accessible name, (**CommandContent** and **CommandList** can share the same label). ```tsx New file Open file Save file No results found. ``` ### CommandGroup naming In the case of several groups, it is recommended to provide an accessible name for each group. - Either by using the `heading` prop on **CommandGroup**, which renders a visible header, - or by using `aria-label` to provide an accessible name without a visible header. `aria-label` takes precedence. ```tsx New file Open file Some help Some more help No results found. ``` ### Disabled options To mark a **CommandOption** as non-interactive, use `aria-disabled="true"` instead of the native `disabled` attribute. This is required because **CommandOption** renders a **div** with `role="option"`, which does not support the native `disabled` attribute. ```tsx New file Open file Save file Some help Some more help No results found. ```