command

README

Command Component

A fast, composable command menu component for search and quick actions, inspired by shadcn/ui's command palette with ⌘K interaction pattern.

Features

• 🔍 Fast search - Real-time filtering with fuzzy matching
• ⌨️ Keyboard navigation - Full keyboard support (arrows, enter, escape, home, end)
• 🎯 ⌘K Dialog - Command palette that opens with Cmd+K / Ctrl+K
• 🎨 Shadcn styling - Beautiful design matching shadcn/ui patterns
• 🧩 Composable API - Build complex command menus with simple components
• ♿ Accessible - Proper ARIA attributes and keyboard navigation
• 🎭 Alpine.js powered - Reactive filtering and selection

Installation

The command component is part of ForgeUI. Import it in your Go code:

import "github.com/xraph/forgeui/components/command"

Basic Usage

Simple Command Menu

command.Command(
    command.CommandInput(),
    command.CommandList(
        command.CommandEmpty("No results found."),
        command.CommandGroup("Suggestions",
            command.CommandItem("Calendar"),
            command.CommandItem("Search Emoji"),
            command.CommandItem("Calculator"),
        ),
        command.CommandSeparator(),
        command.CommandGroup("Settings",
            command.CommandItem("Profile"),
            command.CommandItem("Billing"),
            command.CommandItem("Settings"),
        ),
    ),
)

Command Dialog (⌘K Style)

command.CommandDialog(
    button.Button(g.Text("Open ⌘K")),
    command.CommandInput(),
    command.CommandList(
        command.CommandEmpty("No results found."),
        command.CommandGroup("Actions",
            command.CommandItem("New File"),
            command.CommandItem("New Folder"),
            command.CommandItem("New Document"),
        ),
    ),
)

Components

Command

Main container component that initializes the command menu state and handles keyboard navigation.

command.Command(children ...g.Node)

Features:

• Initializes Alpine.js state for search and selection
• Handles keyboard navigation logic
• Filters items based on search query
• Tracks visible items and selected index

CommandDialog

Wraps the command menu in a dialog that can be triggered with ⌘K/Ctrl+K.

command.CommandDialog(trigger g.Node, children ...g.Node)

Parameters:

• trigger - Element that opens the dialog when clicked
• children - CommandInput, CommandList, and other command components

Features:

• Opens with ⌘K (Mac) or Ctrl+K (Windows/Linux)
• Closes with Escape key
• Auto-focuses input when opened
• Backdrop blur effect
• Focus trap for accessibility

CommandInput

Search input field with icon and optional clear button.

command.CommandInput(opts ...CommandInputOption)

Options:

• WithPlaceholder(text) - Custom placeholder text
• WithIcon(icon) - Custom search icon
• WithShowClear() - Show clear button when input has value
• WithInputClass(class) - Additional CSS classes
• WithInputAttrs(attrs...) - Additional HTML attributes

Example:

command.CommandInput(
    command.WithPlaceholder("Search commands..."),
    command.WithShowClear(),
)

CommandList

Scrollable container for command items with keyboard navigation support.

command.CommandList(children ...g.Node)

Keyboard Navigation:

• ↑/↓ - Navigate through items
• Enter - Select current item
• Home - Jump to first item
• End - Jump to last item
• Escape - Close dialog (when in dialog)

CommandEmpty

Empty state displayed when no items match the search query.

command.CommandEmpty(message string)

Example:

command.CommandEmpty("No results found.")

CommandGroup

Groups related command items with an optional heading.

command.CommandGroup(heading string, children ...g.Node)

Example:

command.CommandGroup("File Operations",
    command.CommandItem("New File"),
    command.CommandItem("Open File"),
    command.CommandItem("Save File"),
)

CommandItem

Individual selectable command item.

command.CommandItem(text string, opts ...CommandItemOption)

Options:

• WithValue(value) - Custom search value (defaults to text)
• WithDisabled(bool) - Disable the item
• WithOnSelect(expr) - Alpine.js expression to execute on selection
• WithItemIcon(icon) - Leading icon
• WithShortcut(keys...) - Keyboard shortcut display
• WithItemClass(class) - Additional CSS classes
• WithItemAttrs(attrs...) - Additional HTML attributes

Example:

command.CommandItem("New File",
    command.WithItemIcon(icons.FilePlus()),
    command.WithShortcut("⌘", "N"),
    command.WithOnSelect("window.location = '/new'"),
)

CommandSeparator

Visual separator between command groups.

command.CommandSeparator()

CommandShortcut

Displays keyboard shortcuts (typically used inside CommandItem).

command.CommandShortcut(keys ...string)

Example:

command.CommandShortcut("⌘", "K")  // ⌘K
command.CommandShortcut("Ctrl", "Shift", "P")  // Ctrl Shift P

Advanced Examples

With Icons and Shortcuts

command.Command(
    command.CommandInput(command.WithPlaceholder("Type a command...")),
    command.CommandList(
        command.CommandEmpty("No commands found."),
        command.CommandGroup("File",
            command.CommandItem("New File",
                command.WithItemIcon(icons.FilePlus()),
                command.WithShortcut("⌘", "N"),
            ),
            command.CommandItem("Open File",
                command.WithItemIcon(icons.FolderOpen()),
                command.WithShortcut("⌘", "O"),
            ),
            command.CommandItem("Save",
                command.WithItemIcon(icons.Save()),
                command.WithShortcut("⌘", "S"),
            ),
        ),
        command.CommandSeparator(),
        command.CommandGroup("Edit",
            command.CommandItem("Copy",
                command.WithItemIcon(icons.Copy()),
                command.WithShortcut("⌘", "C"),
            ),
            command.CommandItem("Paste",
                command.WithItemIcon(icons.Clipboard()),
                command.WithShortcut("⌘", "V"),
            ),
        ),
    ),
)

With Router Integration

command.CommandDialog(
    button.Button(
        g.Text("Search"),
        button.WithVariant(forgeui.VariantOutline),
    ),
    command.CommandInput(),
    command.CommandList(
        command.CommandEmpty("No pages found."),
        command.CommandGroup("Pages",
            command.CommandItem("Dashboard",
                command.WithItemIcon(icons.LayoutDashboard()),
                command.WithOnSelect("window.location = '/dashboard'"),
            ),
            command.CommandItem("Users",
                command.WithItemIcon(icons.Users()),
                command.WithOnSelect("window.location = '/users'"),
            ),
            command.CommandItem("Settings",
                command.WithItemIcon(icons.Settings()),
                command.WithOnSelect("window.location = '/settings'"),
            ),
        ),
    ),
)

With HTMX Actions

command.Command(
    command.CommandInput(),
    command.CommandList(
        command.CommandEmpty("No actions available."),
        command.CommandGroup("Quick Actions",
            command.CommandItem("Create Task",
                command.WithItemIcon(icons.Plus()),
                command.WithItemAttrs(
                    htmx.HXPost("/api/tasks"),
                    htmx.HXSwap("afterbegin"),
                    htmx.HXTarget("#task-list"),
                ),
            ),
            command.CommandItem("Refresh Data",
                command.WithItemIcon(icons.RefreshCw()),
                command.WithItemAttrs(
                    htmx.HXGet("/api/data"),
                    htmx.HXSwap("innerHTML"),
                    htmx.HXTarget("#data-container"),
                ),
            ),
        ),
    ),
)

Disabled Items

command.CommandItem("Premium Feature",
    command.WithItemIcon(icons.Crown()),
    command.WithDisabled(true),
)

Custom Search Values

// Search for "delete" or "remove" will both match this item
command.CommandItem("Delete Item",
    command.WithValue("delete remove trash"),
    command.WithItemIcon(icons.Trash()),
)

Styling

The command component uses CVA (Class Variance Authority) for consistent styling. All components follow shadcn/ui design patterns.

Customization

You can add custom classes to any component:

command.CommandInput(
    command.WithInputClass("border-2 border-primary"),
)

command.CommandItem("Custom",
    command.WithItemClass("text-primary font-bold"),
)

Theme Variables

The component uses these CSS custom properties:

• --popover - Background color
• --popover-foreground - Text color
• --border - Border color
• --accent - Hover/selected background
• --accent-foreground - Hover/selected text
• --muted-foreground - Muted text color

Accessibility

The command component is built with accessibility in mind:

• ✅ Proper ARIA roles and attributes
• ✅ Full keyboard navigation
• ✅ Focus management in dialog mode
• ✅ Screen reader support
• ✅ Focus trap when in dialog
• ✅ Visible focus indicators

Browser Compatibility

Works in all modern browsers that support:

• Alpine.js v3+
• CSS Grid and Flexbox
• ES6+ JavaScript

Related Components

• Dialog - Base dialog component
• Input - Form input component
• Separator - Visual separator
• Icons - Icon system

License

Part of ForgeUI - MIT License

Documentation

Overview

Package command provides a command menu component with search and keyboard navigation.

The Command component is a fast, composable command menu for search and quick actions, inspired by shadcn/ui's command palette with ⌘K interaction pattern.

Basic usage:

command.Command(
    command.CommandInput(),
    command.CommandList(
        command.CommandEmpty("No results found."),
        command.CommandGroup("Suggestions",
            command.CommandItem("Calendar"),
            command.CommandItem("Search Emoji"),
        ),
    ),
)

Index

• func Command(children ...g.Node) g.Node
• func CommandDialog(trigger g.Node, children ...g.Node) g.Node
• func CommandEmpty(message string) g.Node
• func CommandGroup(heading string, children ...g.Node) g.Node
• func CommandInput(opts ...CommandInputOption) g.Node
• func CommandItem(text string, opts ...CommandItemOption) g.Node
• func CommandList(children ...g.Node) g.Node
• func CommandSeparator() g.Node
• func CommandShortcut(keys ...string) g.Node
• type CommandInputOption
  • func WithIcon(icon g.Node) CommandInputOption
  • func WithInputAttrs(attrs ...g.Node) CommandInputOption
  • func WithInputClass(class string) CommandInputOption
  • func WithPlaceholder(text string) CommandInputOption
  • func WithShowClear() CommandInputOption
• type CommandInputProps
• type CommandItemOption
  • func WithDisabled(disabled bool) CommandItemOption
  • func WithItemAttrs(attrs ...g.Node) CommandItemOption
  • func WithItemClass(class string) CommandItemOption
  • func WithItemIcon(icon g.Node) CommandItemOption
  • func WithOnSelect(expr string) CommandItemOption
  • func WithShortcut(keys ...string) CommandItemOption
  • func WithValue(value string) CommandItemOption
• type CommandItemProps

Functions

func Command

func Command(children ...g.Node) g.Node

Command creates a command menu container with search and keyboard navigation.

Example:

command.Command(
    command.CommandInput(),
    command.CommandList(
        command.CommandGroup("Actions",
            command.CommandItem("New File"),
        ),
    ),
)

func CommandDialog

func CommandDialog(trigger g.Node, children ...g.Node) g.Node

CommandDialog creates a command palette dialog that opens with ⌘K/Ctrl+K.

Example:

command.CommandDialog(
    button.Button(g.Text("Open Command")),
    command.CommandInput(),
    command.CommandList(...),
)

func CommandEmpty

func CommandEmpty(message string) g.Node

CommandEmpty displays a message when no results are found.

Example:

command.CommandEmpty("No results found.")

func CommandGroup

func CommandGroup(heading string, children ...g.Node) g.Node

CommandGroup creates a group of related command items with an optional heading.

Example:

command.CommandGroup("Settings",
    command.CommandItem("Profile"),
    command.CommandItem("Billing"),
)

func CommandInput

func CommandInput(opts ...CommandInputOption) g.Node

CommandInput creates a search input for the command menu.

Example:

command.CommandInput(
    command.WithPlaceholder("Type a command..."),
)

func CommandItem

func CommandItem(text string, opts ...CommandItemOption) g.Node

CommandItem creates a selectable command item.

Example:

command.CommandItem("New File",
    command.WithItemIcon(icons.FilePlus()),
    command.WithShortcut("⌘", "N"),
    command.WithOnSelect("console.log('New file')"),
)

func CommandList

func CommandList(children ...g.Node) g.Node

CommandList creates a scrollable container for command items.

Example:

command.CommandList(
    command.CommandEmpty("No results."),
    command.CommandGroup("Items", ...),
)

func CommandSeparator

func CommandSeparator() g.Node

CommandSeparator creates a visual separator between command groups.

Example:

command.CommandSeparator()

func CommandShortcut

func CommandShortcut(keys ...string) g.Node

CommandShortcut displays keyboard shortcuts in a command item.

Example:

command.CommandShortcut("⌘", "K")

Types

type CommandInputOption

type CommandInputOption func(*CommandInputProps)

CommandInputOption is a functional option for configuring command input

func WithIcon

func WithIcon(icon g.Node) CommandInputOption

WithIcon sets a custom icon for the input

func WithInputAttrs

func WithInputAttrs(attrs ...g.Node) CommandInputOption

WithInputAttrs adds custom attributes to the input

func WithInputClass

func WithInputClass(class string) CommandInputOption

WithInputClass adds custom classes to the input container

func WithPlaceholder

func WithPlaceholder(text string) CommandInputOption

WithPlaceholder sets the input placeholder text

func WithShowClear

func WithShowClear() CommandInputOption

WithShowClear shows the clear button when input has value

type CommandInputProps

type CommandInputProps struct {
	Placeholder string
	Icon        g.Node
	ShowClear   bool
	Class       string
	Attrs       []g.Node
}

CommandInputProps defines configuration for command input

type CommandItemOption

type CommandItemOption func(*CommandItemProps)

CommandItemOption is a functional option for configuring command items

func WithDisabled

func WithDisabled(disabled bool) CommandItemOption

WithDisabled disables the command item

func WithItemAttrs

func WithItemAttrs(attrs ...g.Node) CommandItemOption

WithItemAttrs adds custom attributes to the item

func WithItemClass

func WithItemClass(class string) CommandItemOption

WithItemClass adds custom classes to the item

func WithItemIcon

func WithItemIcon(icon g.Node) CommandItemOption

WithItemIcon adds an icon to the command item

func WithOnSelect

func WithOnSelect(expr string) CommandItemOption

WithOnSelect sets the Alpine expression to execute on selection

func WithShortcut

func WithShortcut(keys ...string) CommandItemOption

WithShortcut adds keyboard shortcut display to the item

func WithValue

func WithValue(value string) CommandItemOption

WithValue sets the search value for the item

type CommandItemProps

type CommandItemProps struct {
	Value    string
	Disabled bool
	OnSelect string
	Icon     g.Node
	Shortcut []string
	Class    string
	Attrs    []g.Node
}

CommandItemProps defines configuration for command items