command

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2026 License: MIT Imports: 7 Imported by: 0

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

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

Constants

This section is empty.

Variables

This section is empty.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.