Command

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

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:

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

showHuxCommand(
  context: context,
  commands: commands,
  placeholder: 'Search commands...',
);

Custom Empty State

showHuxCommand(
  context: context,
  commands: commands,
  emptyText: 'No matching commands found',
);

Command Categories

Organize commands by category for better user experience:

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',
    // ...
  ),
];

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

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(),
  ),
];

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

Command Organization: Group related commands by category and use consistent naming conventions.

Shortcut Conflicts: Ensure keyboard shortcuts don’t conflict with system shortcuts or other app shortcuts.

Accessibility: Always provide meaningful labels and descriptions for screen readers.

API Reference

HuxCommand

The main command palette widget.

Constructor

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

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

Getting Started

Components

Advanced

Overview

Basic Usage

Global Keyboard Shortcuts

Command Item Properties

Shortcut Format

Customization

Custom Placeholder

Custom Empty State

Command Categories

Keyboard Navigation

Examples

File Management Commands

Navigation Commands

Best Practices

API Reference

HuxCommand

Constructor

HuxCommandItem

Constructor

HuxCommandShortcuts

Methods

​Overview

​Basic Usage

​Global Keyboard Shortcuts

​Command Item Properties

​Shortcut Format

​Customization

​Custom Placeholder

​Custom Empty State

​Command Categories

​Keyboard Navigation

​Examples

​File Management Commands

​Navigation Commands

​Best Practices

​API Reference

​HuxCommand

​Constructor

​HuxCommandItem

​Constructor

​HuxCommandShortcuts

​Methods

Overview

Basic Usage

Global Keyboard Shortcuts

Command Item Properties

Shortcut Format

Customization

Custom Placeholder

Custom Empty State

Command Categories

Keyboard Navigation

Examples

File Management Commands

Navigation Commands

Best Practices

API Reference

HuxCommand

Constructor

HuxCommandItem

Constructor

HuxCommandShortcuts

Methods