> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command

> A powerful command palette component for quick access to actions and navigation

The Command component provides a searchable command palette that allows users to quickly find and execute actions using keyboard shortcuts or mouse interaction.

## Overview

* **Keyboard Shortcuts**: Open with `CMD+K` (Mac) or `Ctrl+K` (Windows/Linux)
* **Search & Filter**: Real-time filtering as you type
* **Keyboard Navigation**: Arrow keys to navigate, Enter to execute
* **Customizable**: Add your own commands with icons, shortcuts, and categories
* **Accessible**: Full keyboard and screen reader support

## Basic Usage

```dart theme={null}
import 'package:hux/hux.dart';

// Define your commands
final commands = [
  HuxCommandItem(
    id: 'toggle-theme',
    label: 'Toggle Theme',
    description: 'Switch between light and dark mode',
    shortcut: '⌘⇧T',
    icon: LucideIcons.sun,
    category: 'View',
    onExecute: () => print('Theme toggled'),
  ),
  HuxCommandItem(
    id: 'settings',
    label: 'Settings',
    description: 'Open application settings',
    shortcut: '⌘,',
    icon: LucideIcons.settings,
    category: 'Preferences',
    onExecute: () => print('Settings opened'),
  ),
];

// Show the command palette
showHuxCommand(
  context: context,
  commands: commands,
  placeholder: 'Type a command or search...',
  onCommandSelected: (command) {
    print('Selected: ${command.label}');
  },
);
```

## Global Keyboard Shortcuts

For app-wide command palette access, wrap your app with `HuxCommandShortcuts.wrapper`:

```dart theme={null}
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HuxCommandShortcuts.wrapper(
      commands: globalCommands,
      child: MaterialApp(
        home: MyHomePage(),
      ),
    );
  }
}
```

## Command Item Properties

| Property      | Type           | Description                                  |
| ------------- | -------------- | -------------------------------------------- |
| `id`          | `String`       | Unique identifier for the command            |
| `label`       | `String`       | Display name of the command                  |
| `description` | `String?`      | Optional detailed description                |
| `shortcut`    | `String?`      | Keyboard shortcut (e.g., '⌘K', '⌘⇧F')        |
| `icon`        | `IconData?`    | Icon to display next to the command          |
| `category`    | `String?`      | Category for grouping commands               |
| `onExecute`   | `VoidCallback` | Function to execute when command is selected |

## Shortcut Format

Use Apple symbols for shortcuts without '+' signs:

* **Command**: `⌘`
* **Shift**: `⇧`
* **Option**: `⌥`
* **Control**: `⌃`

Examples:

* `⌘K` - Command + K
* `⌘⇧F` - Command + Shift + F
* `⌘⌥T` - Command + Option + T

## Customization

### Custom Placeholder

```dart theme={null}
showHuxCommand(
  context: context,
  commands: commands,
  placeholder: 'Search commands...',
);
```

### Custom Empty State

```dart theme={null}
showHuxCommand(
  context: context,
  commands: commands,
  emptyText: 'No matching commands found',
);
```

### Command Categories

Organize commands by category for better user experience:

```dart theme={null}
final commands = [
  // File operations
  HuxCommandItem(
    id: 'new-file',
    label: 'New File',
    category: 'File',
    // ...
  ),
  
  // Edit operations
  HuxCommandItem(
    id: 'find',
    label: 'Find',
    category: 'Edit',
    // ...
  ),
  
  // View operations
  HuxCommandItem(
    id: 'toggle-sidebar',
    label: 'Toggle Sidebar',
    category: 'View',
    // ...
  ),
];
```

## Keyboard Navigation

* **`CMD+K` / `Ctrl+K`**: Open command palette
* **`↑` / `↓`**: Navigate through commands
* **`Enter`**: Execute selected command
* **`Escape`**: Close command palette
* **Type**: Filter commands by name

## Examples

### File Management Commands

```dart theme={null}
final fileCommands = [
  HuxCommandItem(
    id: 'new-file',
    label: 'New File',
    shortcut: '⌘N',
    icon: LucideIcons.filePlus,
    category: 'File',
    onExecute: () => createNewFile(),
  ),
  HuxCommandItem(
    id: 'open-file',
    label: 'Open File',
    shortcut: '⌘O',
    icon: LucideIcons.folder,
    category: 'File',
    onExecute: () => openFileDialog(),
  ),
  HuxCommandItem(
    id: 'save-file',
    label: 'Save File',
    shortcut: '⌘S',
    icon: LucideIcons.save,
    category: 'File',
    onExecute: () => saveCurrentFile(),
  ),
];
```

### Navigation Commands

```dart theme={null}
final navigationCommands = [
  HuxCommandItem(
    id: 'go-to-dashboard',
    label: 'Go to Dashboard',
    shortcut: '⌘1',
    icon: LucideIcons.home,
    category: 'Navigation',
    onExecute: () => navigateToDashboard(),
  ),
  HuxCommandItem(
    id: 'go-to-settings',
    label: 'Go to Settings',
    shortcut: '⌘,',
    icon: LucideIcons.settings,
    category: 'Navigation',
    onExecute: () => navigateToSettings(),
  ),
];
```

## Best Practices

<Callout type="info">
  **Command Organization**: Group related commands by category and use consistent naming conventions.
</Callout>

<Callout type="warning">
  **Shortcut Conflicts**: Ensure keyboard shortcuts don't conflict with system shortcuts or other app shortcuts.
</Callout>

<Callout type="success">
  **Accessibility**: Always provide meaningful labels and descriptions for screen readers.
</Callout>

## API Reference

### HuxCommand

The main command palette widget.

#### Constructor

```dart theme={null}
HuxCommand({
  required List<HuxCommandItem> commands,
  String placeholder = 'Type a command or search...',
  String emptyText = 'No commands found',
  ValueChanged<HuxCommandItem>? onCommandSelected,
  VoidCallback? onClose,
})
```

### HuxCommandItem

Represents a single command in the palette.

#### Constructor

```dart theme={null}
HuxCommandItem({
  required String id,
  required String label,
  required VoidCallback onExecute,
  String? description,
  String? shortcut,
  IconData? icon,
  String? category,
})
```

### HuxCommandShortcuts

Utility class for global keyboard shortcuts.

#### Methods

* `wrapper()` - Wraps your app to provide global shortcuts
* `handleKeyEvent()` - Returns a key event handler for custom integration