Omnibar

Omnibar is a search overlay in the style of macOS Spotlight. Use it for command palettes and quick navigation.

Usage#

import { Omnibar } from "@clawscale/react/select";

Omnibar takes the shared item props. It is controlled: isOpen shows it, and onClose fires on Escape or a click on the backdrop.

Examples#

Command palette#

A button and a global hotkey open the palette. useHotkeys registers the hotkey, and useMemo keeps the hotkey list stable between renders. resetOnSelect clears the query for the next time.

shiftP

select/omnibar/command-palette.tsx

import { Button, KeyComboTag, MenuItem, useHotkeys } from "@clawscale/react";
import { Omnibar } from "@clawscale/react/select";
import { useMemo, useState } from "react";
import { COMMANDS, type Command } from "../_data";
import { renderCommand } from "../_renderers";

export default function OmnibarCommandPalette() {
  const [isOpen, setIsOpen] = useState(false);
  const [lastCommand, setLastCommand] = useState<Command>();
  const hotkeys = useMemo(
    () => [{ combo: "shift+p", global: true, label: "Open the command palette", onKeyDown: () => setIsOpen(true) }],
    [],
  );
  useHotkeys(hotkeys);
  return (
    <>
      <Button icon="search" text="Command palette" onClick={() => setIsOpen(true)} />
      <KeyComboTag combo="shift+p" />
      <Omnibar<Command>
        isOpen={isOpen}
        items={COMMANDS}
        itemPredicate={(query, command) => command.title.toLowerCase().includes(query.trim().toLowerCase())}
        itemRenderer={renderCommand}
        noResults={<MenuItem disabled text="No commands match." roleStructure="listoption" />}
        onClose={() => setIsOpen(false)}
        onItemSelect={(command) => {
          setLastCommand(command);
          setIsOpen(false);
        }}
        resetOnSelect
      />
      {lastCommand && <span>Last command: {lastCommand.title}</span>}
    </>
  );
}

Many apps open their palette with Cmd + K (mod+k). This site uses that combo for its own search, an Omnibar too, so the example uses Shift + P.

Omnibar renders an overlay, and hotkeys need a hotkeys provider. Clawscale provider sets up both.

Props interface#

interface OmnibarProps extends ListItemsProps<T>@clawscale/react/select

Props	Description
`activeItem`	`T \| CreateNewItem \| null` The currently focused item for keyboard interactions, or `null` to indicate that no item is active. If omitted or `undefined`, this prop will be uncontrolled (managed by the component's state). Use `onActiveItemChange` to listen for updates. Inherited from `ListItemsProps`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`createNewItemFromQuery`	`(query: string) => T \| T[]` If provided, allows new items to be created using the current query string. This is invoked when user interaction causes one or many items to be created, either by pressing the `Enter` key or by clicking on the "Create Item" option. It transforms a query string into one or many items type. Inherited from `ListItemsProps`
`createNewItemPosition`	`"first" \| "last"` = `'last'` Determines the position of the `createNewItem` within the list: first or last. Only relevant when `createNewItemRenderer` is defined. Inherited from `ListItemsProps`
`createNewItemRenderer`	`(query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) => React.JSX.Element \| undefined` Custom renderer to transform the current query string into a selectable "Create Item" option. If this function is provided, a "Create Item" option will be rendered at the end of the list of items. If this function is not provided, a "Create Item" option will not be displayed. Inherited from `ListItemsProps`
`initialContent`	`React.ReactNode \| null` React content to render when query is empty. If omitted, all items will be rendered (or result of `itemListPredicate` with empty query). If explicit `null`, nothing will be rendered when query is empty. Inherited from `ListItemsProps`
`inputProps`	`InputGroupProps` Props to spread to the query `InputGroup`. Use `query` and `onQueryChange` instead of `inputProps.value` and `inputProps.onChange` to control this input.
`isOpen`required	`boolean` Toggles the visibility of the omnibar. This prop is required because the component is controlled.
`itemDisabled`	`keyof T \| ((item: T, index: number) => boolean)` Determine if the given item is disabled. Provide a callback function, or simply provide the name of a boolean property on the item that exposes its disabled state. Inherited from `ListItemsProps`
`itemListPredicate`	`ItemListPredicate<T>` Customize querying of entire `items` array. Return new list of items. This method can reorder, add, or remove items at will. (Supports filter algorithms that operate on the entire set, rather than individual items.) Inherited from `ListItemsProps`
`itemListRenderer`	`ItemListRenderer<T>` Custom renderer for the contents of the dropdown. Inherited from `ListItemsProps`
`itemPredicate`	`ItemPredicate<T>` Customize querying of individual items. Inherited from `ListItemsProps`
`itemRenderer`required	`ItemRenderer<T>` Custom renderer for an item in the dropdown list. Receives a boolean indicating whether this item is active (selected by keyboard arrows) and an `onClick` event handler that should be attached to the returned element. Inherited from `ListItemsProps`
`items`required	`T[]` Array of items in the list. Inherited from `ListItemsProps`
`itemsEqual`	`ItemsEqualProp<T>` Specifies how to test if two items are equal. By default, simple strict equality (`===`) is used to compare two items. Inherited from `ListItemsProps`
`noResults`	`React.ReactNode` React content to render when filtering items returns zero results. If omitted, nothing will be rendered in this case. Inherited from `ListItemsProps`
`onActiveItemChange`	`(activeItem: T \| null, isCreateNewItem: boolean) => void` Invoked when user interaction should change the active item: arrow keys move it up/down in the list, selecting an item makes it active, and changing the query may reset it to the first item in the list if it no longer matches the filter. Inherited from `ListItemsProps`
`onClose`	`(event?: React.SyntheticEvent<HTMLElement>) => void` A callback that is invoked when user interaction causes the omnibar to close, such as clicking on the overlay or pressing the `esc` key (if enabled). Receives the event from the user's interaction, if there was an event (generally either a mouse or key event).
`onItemSelect`required	`(item: T, event?: React.SyntheticEvent<HTMLElement>) => void` Callback invoked when an item from the list is selected, typically by clicking or pressing `enter` key. Inherited from `ListItemsProps`
`onItemsPaste`	`(items: T[]) => void` Callback invoked when multiple items are selected at once via pasting. Inherited from `ListItemsProps`
`onQueryChange`	`(query: string, event?: React.ChangeEvent<HTMLInputElement>) => void` Callback invoked when the query string changes. Inherited from `ListItemsProps`
`overlayProps`	`Partial<OverlayProps>` Props to spread to `Overlay`.
`query`	`string` Query string passed to `itemListPredicate` or `itemPredicate` to filter items. This value is controlled: its state must be managed externally by attaching an `onChange` handler to the relevant element in your `renderer` implementation. Inherited from `ListItemsProps`
`resetOnQuery`	`boolean` = `true` Whether the active item should be reset to the first matching item _every time the query changes_ (via prop or by user input). Inherited from `ListItemsProps`
`resetOnSelect`	`boolean` = `false` Whether the active item should be reset to the first matching item _when an item is selected_. The query will also be reset to the empty string. Inherited from `ListItemsProps`
`scrollToActiveItem`	`boolean` = `true` When `activeItem` is controlled, whether the active item should _always_ be scrolled into view when the prop changes. If `false`, only changes that result from built-in interactions (clicking, querying, or using arrow keys) will scroll the active item into view. Ignored if the `activeItem` prop is omitted (uncontrolled behavior). Inherited from `ListItemsProps`