CommandBar Component
The CommandBar component provides a powerful command palette interface with keyboard navigation, hotkey support, and customizable styling. It features intelligent search filtering, priority-based sorting, and support for both regular and fixed bottom groups.
Features
- Keyboard Navigation: Full arrow key navigation and Enter to select
- Hotkey Support: Register activation events for individual commands
- Intelligent Search: Custom search functions with priority scoring
- Color Variants: Multiple color schemes for visual categorization
- Fixed Bottom Group: Persistent commands that stay visible during scrolling
- Cedar Editor Integration: Uses Cedar’s rich text editor for input
- Context Badges: Shows selected context with the integrated ContextBadgeRow
- Spell System: Automatic hotkey registration using Cedar’s spell system
Import
import { CommandBar } from 'cedar-os-components/CommandBar/CommandBar';
import type {
CommandBarItem,
CommandBarGroup,
CommandBarContents,
} from 'cedar-os-components/CommandBar/CommandBar';
Basic Usage
import { CommandBar } from 'cedar-os-components/CommandBar/CommandBar';
import { ActivationMode } from 'cedar-os';
const [isOpen, setIsOpen] = useState(false);
const contents: CommandBarContents = {
groups: [
{
id: 'actions',
heading: 'Actions',
items: [
{
id: 'save',
label: 'Save Document',
description: 'Save the current document',
icon: '💾',
onSelect: () => console.log('Save clicked'),
activationEvent: 'cmd+s',
activationMode: ActivationMode.TRIGGER,
},
{
id: 'copy',
label: 'Copy Text',
description: 'Copy selected text to clipboard',
icon: '📋',
onSelect: () => console.log('Copy clicked'),
activationEvent: 'cmd+c',
},
],
},
],
};
<CommandBar
open={isOpen}
contents={contents}
onClose={() => setIsOpen(false)}
placeholder='Type a command or search...'
/>;
Advanced Usage
With Color Variants and Priority Scoring
const advancedContents: CommandBarContents = {
groups: [
{
id: 'file',
heading: 'File Operations',
items: [
{
id: 'new-file',
label: 'New File',
description: 'Create a new document',
icon: '📄',
color: 'blue',
onSelect: () => createNewFile(),
activationEvent: 'cmd+n',
// Custom search function
searchFunction: (searchText, item) => {
return (
item.label.toLowerCase().includes(searchText) ||
'create document'.includes(searchText)
);
},
// Higher priority for exact matches
priorityFunction: (searchText, item) => {
if (item.label.toLowerCase().startsWith(searchText)) return 10;
if (item.label.toLowerCase().includes(searchText)) return 5;
return 0;
},
},
{
id: 'delete-file',
label: 'Delete File',
description: 'Permanently delete the current file',
icon: '🗑️',
color: 'red',
onSelect: () => deleteFile(),
activationEvent: 'cmd+shift+d',
},
],
},
],
fixedBottomGroup: {
id: 'quick-actions',
heading: 'Quick Actions',
items: [
{
id: 'help',
label: 'Help',
icon: '❓',
color: 'purple',
onSelect: () => showHelp(),
activationEvent: 'F1',
},
{
id: 'settings',
label: 'Settings',
icon: '⚙️',
color: 'gray',
onSelect: () => openSettings(),
activationEvent: 'cmd+comma',
},
],
},
};
With Controlled Collapse State
const [collapsed, setCollapsed] = useState(false);
<CommandBar
open={isOpen}
contents={contents}
collapsed={collapsed}
onClose={() => setIsOpen(false)}
onSearchChange={(searchText) => {
console.log('Search changed:', searchText);
// Auto-expand when typing
if (searchText && collapsed) {
setCollapsed(false);
}
}}
/>;
Props
CommandBarProps
Whether the command bar is visible
contents
CommandBarContents
required
Command bar contents organized into groups
placeholder
string
default:"Type a command or search..."
Placeholder text for the search input
Additional CSS classes for the container
Callback when the command bar should close
Whether the command bar is in collapsed state (only shows search bar)
onSearchChange
(searchText: string) => void
Callback when search text changes
CommandBarItem
Unique identifier for the item
Display text for the item
Callback when item is selected
Optional description text shown below the label
Optional icon (emoji string or React component)
Optional hotkey for triggering this command
activationMode
ActivationMode
default:"TRIGGER"
How the hotkey should behave (TRIGGER, HOLD, TOGGLE)
Whether the item is disabled
Color variant for styling (‘blue’, ‘green’, ‘purple’, ‘orange’, ‘pink’,
‘amber’, ‘red’, ‘indigo’, ‘white’)
searchFunction
(searchText: string, item: CommandBarItem) => boolean
Custom function to determine if item matches search text
priorityFunction
(searchText: string, item: CommandBarItem) => number
Function to score items for better ordering (higher scores appear first)
Whether to ignore hotkey when typing in input elements (auto-determined by
default)
CommandBarGroup
Unique identifier for the group
Optional heading text for the group
CommandBarContents
groups
CommandBarGroup[]
required
Array of command groups
Optional group that stays at the bottom outside scroll area
Color Variants
The CommandBar supports the following color variants for visual categorization:
blue - Blue theme with hover statesgreen - Green theme for success/create actionspurple - Purple theme for special featuresorange - Orange theme for warningspink - Pink theme for favorites/highlightsamber - Amber theme for pending statesred - Red theme for destructive actionsindigo - Indigo theme for navigationwhite - Clean white theme
Keyboard Shortcuts
- ⌘K - Toggle focus between input and command list
- Escape - Unfocus input or close command bar
- Arrow Keys - Navigate through commands
- Enter - Execute selected command
- Tab - Focus the search input
Integration with Cedar
The CommandBar automatically integrates with Cedar’s spell system to register hotkeys and uses the Cedar editor for rich text input with context support.
Spell Registration
Each CommandBarItem with an activationEvent automatically registers a spell that:
- Respects the
activationMode setting
- Only triggers when the command bar is open
- Automatically closes the command bar after execution
- Handles input element detection based on modifier keys
Context Integration
The integrated ContextBadgeRow shows selected context from Cedar’s agent input context system, allowing users to see and manage their current context selection.
Examples
File Manager Command Bar
const fileManagerCommands: CommandBarContents = {
groups: [
{
id: 'file-ops',
heading: 'File Operations',
items: [
{
id: 'new-folder',
label: 'New Folder',
icon: '📁',
color: 'blue',
onSelect: () => createFolder(),
activationEvent: 'cmd+shift+n',
},
{
id: 'upload',
label: 'Upload Files',
icon: '⬆️',
color: 'green',
onSelect: () => uploadFiles(),
activationEvent: 'cmd+u',
},
],
},
{
id: 'view',
heading: 'View Options',
items: [
{
id: 'grid-view',
label: 'Grid View',
icon: '⊞',
onSelect: () => setViewMode('grid'),
activationEvent: 'cmd+1',
},
{
id: 'list-view',
label: 'List View',
icon: '☰',
onSelect: () => setViewMode('list'),
activationEvent: 'cmd+2',
},
],
},
],
};
Search-Focused Command Bar
const searchCommands: CommandBarContents = {
groups: [
{
id: 'search-results',
items: results.map((result) => ({
id: result.id,
label: result.title,
description: result.description,
icon: result.icon,
onSelect: () => openResult(result),
// Boost exact matches
priorityFunction: (searchText, item) => {
const text = searchText.toLowerCase();
const title = item.label.toLowerCase();
if (title === text) return 100;
if (title.startsWith(text)) return 50;
if (title.includes(text)) return 25;
return 0;
},
})),
},
],
};
Styling
The CommandBar uses Tailwind CSS classes and supports dark mode. Color variants are implemented using opacity-based backgrounds that work well in both light and dark themes.
Custom styling can be applied through the className prop or by overriding the default Tailwind classes.
