kbar

To render the command palette UI, use the provided component hierarchy inside KBarProvider. This structure ensures the menu is rendered outside the root node and handles animations and positioning.

Required components:

• KBarPortal: Renders the content outside the root node.
• KBarPositioner: Centers the content.
• KBarAnimator: Handles show/hide and height animations.
• KBarSearch: The search input field.

import {
  KBarProvider,
  KBarPortal,
  KBarPositioner,
  KBarAnimator,
  KBarSearch
} from "kbar";

// Inside your component return:
<KBarProvider actions={actions}>
  <KBarPortal>
    <KBarPositioner>
      <KBarAnimator>
        <KBarSearch />
      </KBarAnimator>
    </KBarPositioner>
  </KBarPortal>
  <MyApp />
</KBarProvider>

Use the useMatches hook to get a flattened list of results (including group names) and the KBarResults component to render them efficiently using virtualization.

The onRender prop in KBarResults provides the item and its active state, allowing you to customize the appearance of both group headers (strings) and action items (objects).

import {
  KBarResults,
  useMatches,
  NO_GROUP,
} from "kbar";

function RenderResults() {
  const { results } = useMatches();

  return (
    <KBarResults
      items={results}
      onRender={({ item, active }) =>
        typeof item === "string" ? (
          <div>{item}</div>
        ) : (
          <div
            style={{
              background: active ? "#eee" : "transparent",
            }}
          >
            {item.name}
          </div>
        )
      }
    />
  );
}

Install the kbar package via npm to add a command palette interface to your React application.

npm install kbar

The following hooks are available for interacting with the command palette state:

• useMatches: Returns a flattened list of results and group names based on the current search query. The returned array format is ["Section name", Action, Action, "Another section name", Action, Action].

The following components are used to build the command palette interface:

• KBarProvider: The context provider that holds actions and state.
• KBarPortal: Renders the menu outside the main application DOM tree.
• KBarPositioner: Handles the positioning/centering of the menu.
• KBarAnimator: Manages entry/exit and height animations.
• KBarSearch: The input field for user queries.
• KBarResults: A virtualized list component for rendering search results.

The IKBarContext provides access to the internal state and configuration of kbar. It includes:

• getState(): Returns the current KBarState (including searchQuery, activeIndex, and visualState).
• query: Provides the KBarQuery methods for interaction.
• subscribe(collector, cb): Allows subscribing to state changes.
• options: Returns the current KBarOptions.

export interface IKBarContext {
  getState: () => KBarState;
  query: KBarQuery;
  subscribe: (
    collector: <C>(state: KBarState) => C,
    cb: <C>(collected: C) => void
  ) => void;
  options: KBarOptions;
}

The kbar package provides a suite of components and hooks to build a command palette interface. Key exports include:

• Hooks: useKBar for accessing the kbar state, useMatches for finding matching actions, and useRegisterActions for registering your command list.
• Components: KBarContextProvider to wrap your application, KBarSearch for the input field, KBarResults for displaying matches, KBarPortal and KBarPositioner for layout and rendering, and KBarAnimator for transitions.
• Core: action for action definitions and types for TypeScript definitions.

The KBarSearch component provides a controlled input field for the kbar interface. It integrates with the useKBar hook to manage search queries, handle focus, and manage accessibility attributes like aria-controls and aria-activedescendant.

Key features:

• Automatically manages the search query via query.setSearch.
• Automatically focuses the input when the root action changes.
• Dynamically updates the placeholder: it shows the name of the currentRootAction if one is active, otherwise it falls back to defaultPlaceholder or the default string "Type a command or search…".
• Supports standard HTMLInputElement props (e.g., onChange, onKeyDown).
• Clears the search query when the component unmounts or when the root action changes.