Components | omverse-ui

Overview

Use CommandBar to help experienced and keyboard-oriented users find and execute actions without navigating through several interface layers.

Workspace commands

Live preview

Search the command set or use Arrow keys to change the active result.

Selected: Try a command

WorkspaceCommands.tsx

tsx

1import { CommandBar, type CommandBarCommand } from 'omverse-ui'
2 
3const commands: CommandBarCommand[] = [
{
  "id": "create",
  "label": "Create project",
  "group": "Actions",
  "description": "Start a new enterprise project",
  "icon": "plus",
  "shortcut": [
    "⌘",
    "N"
  ]
},
{
  "id": "invite",
  "label": "Invite people",
  "group": "Actions",
  "description": "Add members to this workspace",
  "icon": "users"
},
{
  "id": "settings",
  "label": "Workspace settings",
  "group": "Navigate",
  "description": "Manage security and defaults",
  "icon": "settings",
  "shortcut": [
    "G",
    "S"
  ]
},
{
  "id": "audit",
  "label": "Audit reports",
  "group": "Navigate",
  "description": "Review governance activity",
  "icon": "file-text"
}
40]
41 
42<CommandBar
commands={commands}
mode="inline"
title="Workspace commands"
placeholder="Search commands..."
onCommandSelect={(command) => {
  console.log(`Selected: ${command.label}`)
}}
50/>

Anatomy

CommandBar combines a named search field, grouped results, active command, shortcut hints, and keyboard guidance.

⌕Search commands…⌘ K

Actions

Create projectStart a new enterprise project⌘ N

Navigate

Workspace settings

12345

1
Command search
Filters the command set while retaining keyboard focus.
2
Command group
Organizes related actions and destinations under a short heading.
3
Active command
Identifies the result that Enter will execute.
4
Shortcut hint
Teaches a direct keyboard path for a familiar command.
5
Keyboard guidance
Summarizes navigation and execution keys.

When to use

Use CommandBar when an application has many actions or destinations that experienced users need to reach quickly.

Accelerate broad workflows
Search commands across projects, people, settings, reports, and navigation.
Support keyboard-first work
Offer a global shortcut and predictable result navigation.
Expose contextual commands
Build the command set from current permissions, selection, and workspace state.

When not to use

CommandBar should complement discoverable navigation and controls, not replace them.

Avoid

Do not hide primary actions
Keep frequent and critical actions visible in Toolbar or page content.
Do not use for value selection
Use Combobox when the result becomes a form value.
Do not overload novice workflows
Maintain ordinary navigation and contextual help alongside commands.

Variants

Mode and width adapt CommandBar to global command palettes and embedded workspace search.

Overlay

Provides a modal global command surface with focus containment.

Inline

Embeds command search within a page or productivity workspace.

Grouped

Separates actions, navigation, records, and other command families.

Widths

Small, medium, and large accommodate command metadata.

States

CommandBar coordinates visibility, query, active result, execution availability, progress, and empty feedback.

State	Trigger	Visual response	Interaction
Closed	Palette is inactive	No overlay surface	Global shortcut opens
Open	Shortcut or trigger activates	Search and grouped commands	Input receives focus
Active	Keyboard or pointer movement	Tonal row highlight	Enter executes
Disabled command	Action is unavailable	Reduced emphasis	Cannot execute
Loading	Commands are resolving	Progress and loading message	Query remains visible
Empty	No command matches	No-command message	Query remains editable

Behavior

CommandBar owns discovery and invocation mechanics while applications own command availability, authorization, navigation, and side effects.

Global shortcut

Command/Ctrl+K toggles the overlay without entering text.

Active descendant

Focus stays in search while results are navigated.

Filtering

Default matching covers labels, descriptions, groups, and keywords.

Execution

Enter runs the active enabled command and normally closes the palette.

Accessibility

Overlay CommandBar is a named modal dialog containing an editable combobox and grouped listbox with active-descendant navigation.

Key	Action
`⌘K`	Opens or closes the global command surface.
`↑↓`	Moves the active command.
`HomeEnd`	Moves to the first or last result.
`Enter`	Executes the active enabled command.
`Esc`	Closes and returns focus.
`Tab`	Cycles through focusable overlay controls.

Give the command surface and result list concise names.
Keep DOM focus in the search input during result navigation.
Expose the active command with aria-activedescendant.
Announce disabled commands without allowing execution.
Trap and return focus in overlay mode.
Show shortcut hints as supplemental text, never the only label.

Content guidelines

Command labels should describe an immediate result and remain distinguishable when removed from their original screen.

Start with a verb

Name executable commands by their outcome.

ExampleCreate project

Name destinations

Use destination titles for navigation commands.

ExampleWorkspace settings

Add concise context

Use descriptions to distinguish similar commands.

ExampleManage security and defaults

Group by intent

Use short parallel headings.

ExampleActions, Navigate

Examples

Controlled query and filtering support server-ranked or permission-aware command sets.

Interactive command menu

Live preview

Try filtering the realistic grouped command set.

Selected: Try a command

ControlledCommands.tsx

tsx

1<CommandBar
commands={commands}
inputValue={query}
onInputValueChange={setQuery}
filterCommand={(command, value) => command.label.toLowerCase().includes(value.toLowerCase())}
loading={isLoading}
onCommandSelect={trackCommand}
mode="inline"
9/>

Props / API

CommandBar extends div attributes; CommandBarCommand defines identity, content, grouping, discovery keywords, availability, shortcut hints, and execution.

Props

PropTypeDefaultDescription

commandsreadonly CommandBarCommand[]requiredCommands available for search and execution.

openbooleanundefinedControlled visibility.

defaultOpenbooleanfalseInitial uncontrolled visibility.

onOpenChange(open: boolean) => voidundefinedRuns whenever visibility changes.

inputValuestringundefinedControlled search query.

defaultInputValuestring''Initial uncontrolled query.

onInputValueChange(value: string) => voidundefinedRuns whenever the query changes.

titlestring'Command menu'Accessible title for the command surface.

placeholderstring'Search commands…'Search prompt.

onCommandSelect(command) => voidundefinedRuns after an enabled command is selected.

filterCommand(command, query) => booleanbuilt-in text matchCustom command filtering logic.

loadingbooleanfalseShows asynchronous command progress.

emptyStateReactNode'No commands found.'Content shown when no command matches.

closeOnSelectbooleantrueCloses after command execution.

hotkeybooleantrueEnables the global Command/Ctrl+K shortcut.

returnFocusRefRefObject<HTMLElement>previous focusElement focused after an overlay closes.

mode'overlay' | 'inline''overlay'Chooses modal palette or embedded search.

size'sm' | 'md' | 'lg''md'Controls maximum command surface width.

Use adjacent patterns based on whether people are executing commands, choosing values, navigating, or acting on current content.

CommandBar

Workspace commands

Recommended

Avoid

Overlay

Inline

Grouped

Widths

Global shortcut

Active descendant

Filtering

Execution

Start with a verb

Name destinations

Add concise context

Group by intent

Workspace commands