# KBar — Fast Command Palette Interface for React

> A portable, extensible command+k interface for React applications that provides fuzzy search, keyboard navigation, and nested action support.

## Install

Save in your project root:

# KBar — Fast Command Palette Interface for React

## Quick Use
```bash
npm install kbar
```
```jsx
import { KBarProvider, KBarPortal, KBarPositioner, KBarAnimator, KBarSearch, KBarResults, useMatches } from 'kbar';

const actions = [
  { id: 'home', name: 'Home', shortcut: ['g', 'h'], perform: () => (window.location.pathname = '/') },
  { id: 'docs', name: 'Documentation', shortcut: ['g', 'd'], perform: () => (window.location.pathname = '/docs') },
];

function Results() {
  const { results } = useMatches();
  return <KBarResults items={results} onRender={({ item }) => typeof item === 'string' ? <div>{item}</div> : <div>{item.name}</div>} />;
}

function App() {
  return (
    <KBarProvider actions={actions}>
      <KBarPortal>
        <KBarPositioner>
          <KBarAnimator>
            <KBarSearch />
            <Results />
          </KBarAnimator>
        </KBarPositioner>
      </KBarPortal>
    </KBarProvider>
  );
}
```

## Introduction
KBar adds a command palette (Cmd+K or Ctrl+K) to React applications, similar to the interfaces found in VS Code, Slack, and Linear. It provides a composable set of React components for the search input, results list, and positioning, along with a data-driven action system that supports keyboard shortcuts, nested sub-actions, and dynamic action registration.

## What KBar Does
- Provides a Cmd+K / Ctrl+K triggered command palette overlay
- Fuzzy-searches registered actions by name and keywords in real time
- Supports nested actions for hierarchical navigation (e.g., Settings > Theme > Dark)
- Allows dynamic action registration and removal at runtime
- Handles keyboard navigation with arrow keys, Enter, and Escape

## Architecture Overview
KBar uses a React context provider (KBarProvider) to manage a store of actions and UI state (open, search query, active action path). The search component dispatches query updates to the store, which filters actions using a built-in fuzzy matching algorithm. Results are rendered via a virtualized list component for performance with large action sets. The portal, positioner, and animator components handle overlay placement and enter/exit transitions. Actions can be static (defined at provider mount) or dynamic (registered by child components via useRegisterActions).

## Installation & Configuration
- Install via npm: `npm install kbar`
- Wrap your app in KBarProvider with an actions array
- Compose KBarPortal, KBarPositioner, KBarAnimator, KBarSearch, and KBarResults inside the provider
- Define actions with id, name, optional shortcut, and a perform callback
- Use useRegisterActions to add context-specific actions from nested components

## Key Features
- Composable architecture with separate components for each UI concern
- Dynamic action registration from any component in the tree
- Nested actions for multi-level navigation menus
- Built-in keyboard shortcut binding for individual actions
- Fully stylable via className props on each component

## Comparison with Similar Tools
- **cmdk** — Pacocoursey command menu with opinionated styling; less composable architecture
- **ninja-keys** — web component based; framework-agnostic but less React-idiomatic
- **react-command-palette** — older library with fewer features and less active development
- **Spotlight (Mantine)** — tied to the Mantine UI ecosystem
- **VS Code command palette** — inspiration for KBar; not a reusable library

## FAQ
**Q: How do I trigger the palette with a custom keyboard shortcut?**
A: KBar opens on Cmd+K by default. You can customize the toggle shortcut by passing a custom toggle action or handling it via the useKBar hook.

**Q: Can I add actions dynamically based on the current page?**
A: Yes. Use the useRegisterActions hook in any component to register and unregister actions tied to that component's lifecycle.

**Q: Does KBar support sections or groups in the results?**
A: Yes. Actions with a section property are grouped under section headers in the results list.

**Q: How do I style the command palette?**
A: Each component (KBarAnimator, KBarSearch, KBarResults) accepts style and className props for custom CSS.

## Sources
- https://github.com/timc1/kbar
- https://kbar.vercel.app

---
Source: https://tokrepo.com/en/workflows/asset-4621ed21
Author: AI Open Source