Omnibar

Introduction

Omnibar<T> is a macOS Spotlight-style typeahead component composing Overlay and QueryList<T>. Usage is similar to Select<T>: provide your items and a predicate to customize the filtering algorithm. The component is fully controlled via the isOpen prop, which means you can decide exactly how to trigger the component. The following example responds to a button.

Examples

Usage

Omnibar

To render an Omnibar, you must supply a list of items, an itemRenderer function, to determine how each item should be rendered in the UI, and an itemPredicate function to filter items based on the query input.

import React from "react";
import { Omnibar, Button } from "@commure/components-foundation";
class MyOmnibar extends React.Component {
constructor(props) {
super(props);
this.state = { showOmnibar: false };
}
render() {
return (
<React.Fragment>
<Button onClick={() => this.setState({ showOmnibar: true })}>
Show Omnibar
</Button>
<Omnibar
isOpen={this.state.showOmnibar}
items={[
{ title: "Pizza" },
{ title: "Hamburger" },
{ title: "Sushi" },
{ title: "Tacos" },
{ title: "Burrito" }
]}
itemPredicate={(query, item) =>
item.title.toLowerCase().includes(query.toLowerCase())
}
itemRenderer={({ title }, { index }) => (
<div key={index}>
<h5>{title}</h5>
</div>
)}
onClose={() => this.setState({ showOmnibar: false })}
/>
</React.Fragment>
);
}
}
export default MyOmnibar;

API Reference

Omnibar

Prop NameRequired?TypeDescription
activeItemfalseT | ICreateNewItem | nullThe 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.
createNewItemFromQueryfalse(query: string) => TIf provided, allows new items to be created using the current query string. This is invoked when user interaction causes a new item to be created, either by pressing the `Enter` key or by clicking on the "Create Item" option. It transforms a query string into an item type.
createNewItemRendererfalse(query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) => Element | undefinedCustom 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.
initialContentfalseReact.ReactNode | nullReact 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. This prop is ignored if a custom `itemListRenderer` is supplied.
inputPropsfalseIInputGroupProps & HTMLInputPropsProps to spread to the query `InputGroup`. Use `query` and `onQueryChange` instead of `inputProps.value` and `inputProps.onChange` to control this input.
isOpentruebooleanToggles the visibility of the omnibar. This prop is required because the component is controlled.
itemDisabledfalsekeyof T | (item: T, index: number) => booleanDetermine 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.
itemListPredicatefalseItemListPredicate<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.) If `itemPredicate` is also defined, this prop takes priority and the other will be ignored.
itemListRendererfalseItemListRenderer<T>Custom renderer for the contents of the dropdown. The default implementation invokes `itemRenderer` for each item that passes the predicate and wraps them all in a `Menu` element. If the query is empty then `initialContent` is returned, and if there are no items that match the predicate then `noResults` is returned.
itemPredicatefalseItemPredicate<T>Customize querying of individual items. __Filtering a list of items.__ This function is invoked to filter the list of items as a query is typed. Return `true` to keep the item, or `false` to hide. This method is invoked once for each item, so it should be performant. For more complex queries, use `itemListPredicate` to operate once on the entire array. For the purposes of filtering the list, this prop is ignored if `itemListPredicate` is also defined. __Matching a pasted value to an item.__ This function is also invoked to match a pasted value to an existing item if possible. In this case, the function will receive `exactMatch=true`, and the function should return true only if the item _exactly_ matches the query. For the purposes of matching pasted values, this prop will be invoked even if `itemListPredicate` is defined.
itemRenderertrueItemRenderer<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.
itemstrueT[]Array of items in the list.
itemsEqualfalseItemsEqualProp<T>Specifies how to test if two items are equal. By default, simple strict equality (`===`) is used to compare two items. If your items have a unique identifier field, simply provide the name of a property on the item that can be compared with strict equality to determine equivalence: `itemsEqual="id"` will check `a.id === b.id`. If more complex comparison logic is required, provide an equality comparator function that returns `true` if the two items are equal. The arguments to this function will never be `null` or `undefined`, as those values are handled before calling the function.
noResultsfalseReact.ReactNodeReact content to render when filtering items returns zero results. If omitted, nothing will be rendered in this case. This prop is ignored if a custom `itemListRenderer` is supplied.
onActiveItemChangefalse(activeItem: T | null, isCreateNewItem: boolean) => voidInvoked 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. If the "Create Item" option is displayed and currently active, then `isCreateNewItem` will be `true` and `activeItem` will be `null`. In this case, you should provide a valid `ICreateNewItem` object to the `activeItem` _prop_ in order for the "Create Item" option to appear as active. __Note:__ You can instantiate a `ICreateNewItem` object using the `getCreateNewItem()` utility exported from this package.
onClosefalse(event?: SyntheticEvent<HTMLElement>) => voidA 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). Note that due to controlled usage, this component will not actually close itself until the `isOpen` prop becomes `false`. .
onItemSelecttrue(item: T, event?: SyntheticEvent<HTMLElement>) => voidCallback invoked when an item from the list is selected, typically by clicking or pressing `enter` key.
onItemsPastefalse(items: T[]) => voidCallback invoked when multiple items are selected at once via pasting.
onQueryChangefalse(query: string, event?: ChangeEvent<HTMLInputElement>) => voidCallback invoked when the query string changes.
overlayPropsfalsePartial<IOverlayProps>Props to spread to `Overlay`.
queryfalsestringQuery 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.
resetOnQueryfalsebooleanWhether the active item should be reset to the first matching item _every time the query changes_ (via prop or by user input).
resetOnSelectfalsebooleanWhether 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.
scrollToActiveItemfalsebooleanWhen `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).

Related Reading

Blueprint Reference
Select Documentation