# Command
> A searchable command menu, as a dialog or composed inline from parts.
Source: https://shellui.dev/docs/v0.4/components/advanced/command
`Command` was rewritten in v0.4. It filters as you type, moves with the arrow keys, groups items under headings, and runs the selected item's `Action`. It has two modes:
- **Dialog:** pass `Commands` and bind `IsOpen`. You open it yourself, from a button or your own shortcut.
- **Composed:** put `CommandInput`, `CommandList`, `CommandGroup` and `CommandOption` inside it to render the menu inline, for example in a popover or a sidebar.
For a dialog that opens on Ctrl+K without extra code, use [Command Palette](https://shellui.dev/docs/v0.4/components/advanced/command-palette.md).
## Installation
```bash
shellui add command
```
This also installs the parts and the `CommandItem` model.
## Usage
### Dialog
Each `CommandItem` can carry an `Action`. Selecting an item closes the dialog, runs its `Action`, then raises `CommandSelected`.
```razor
Selected: @selected ยท Action ran @runs time(s)
@code {
private bool open;
private int runs;
private string selected = "none";
private List commands = new();
protected override void OnInitialized()
{
commands =
[
new() { Title = "New file", Description = "Create an empty file", Shortcut = "Ctrl+N", Group = "File", Action = RunAsync },
new() { Title = "Open folder", Shortcut = "Ctrl+O", Group = "File", Action = RunAsync },
new() { Title = "Toggle theme", Description = "Switch between light and dark", Group = "View", Action = RunAsync },
new() { Title = "Zoom in", Shortcut = "Ctrl++", Group = "View", Action = RunAsync },
];
}
private Task RunAsync()
{
runs++;
return Task.CompletedTask;
}
}
```
> **Changed from 0.3**
>
> In 0.3, `Command` ignored `CommandItem.Action` and only raised `CommandSelected`. If you ran the action yourself in a `CommandSelected` handler, remove that call, or it runs twice.
### Composed from parts
`CommandOption.Value` is the text matched against the search, and `OnSelect` runs when the option is chosen. Groups hide when none of their options match, and `CommandEmpty` shows when nothing does.
```razor
No results found.CalendarSearch emojiCalculatorProfileBilling
Selected: @last
@code {
private string last = "none";
}
```
The part is called `CommandOption` because `CommandItem` is the model class.
## Keyboard
| Key | Action |
|-----|--------|
| `Up` / `Down` | Move through the results |
| `Home` / `End` | Jump to the first or last result |
| `Enter` | Select the highlighted result |
| `Esc` | Close the dialog |
## API Reference
### Command
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `IsOpen` | `bool` | `false` | Whether the dialog is open; use `@bind-IsOpen` |
| `IsOpenChanged` | `EventCallback` | - | Fires when the dialog opens or closes |
| `Commands` | `List` | empty | Items for the dialog |
| `CommandSelected` | `EventCallback` | - | Fires after the item's `Action` has run |
| `Placeholder` | `string` | `"Type a command or search..."` | Search placeholder |
| `ChildContent` | `RenderFragment?` | `null` | Set to compose the menu from parts |
| `Class` | `string?` | `null` | Additional CSS classes |
### CommandItem
| Property | Type | Description |
|----------|------|-------------|
| `Title` | `string` | Text shown and searched |
| `Description` | `string?` | Second line; also searched |
| `Icon` | `string?` | SVG markup shown before the title |
| `Shortcut` | `string?` | Key hint, such as `Ctrl+N`; split on `+` |
| `Group` | `string?` | Heading the item is listed under |
| `Action` | `Func?` | Runs when the item is selected |
### Parts
| Component | Parameters | Purpose |
|-----------|------------|---------|
| `CommandInput` | `Placeholder`, `AutoFocus` (default `true`) | The search box |
| `CommandList` | - | The scrolling list |
| `CommandGroup` | `Heading` | A labelled group of options |
| `CommandOption` | `Value`, `OnSelect`, `Disabled` | One selectable row |
| `CommandEmpty` | - | Shown when no option matches |
| `CommandSeparator` | - | A divider between groups |
Each part also takes `ChildContent` and `Class`.
## Accessibility
- The search box is `role="combobox"` and the list is `role="listbox"` with `role="option"` rows
- `aria-selected` follows the highlighted row, and `aria-disabled` marks disabled options
- The dialog is `role="dialog"` with `aria-modal="true"` and focuses the search box when it opens