Skip to main content
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

PropertyTypeDescription
idStringUnique identifier for the command
labelStringDisplay name of the command
descriptionString?Optional detailed description
shortcutString?Keyboard shortcut (e.g., ‘⌘K’, ’⌘⇧F’)
iconIconData?Icon to display next to the command
categoryString?Category for grouping commands
onExecuteVoidCallbackFunction 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',
    // ...
  ),
];

​
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

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
⌘I