Balance Logo
Balance
Reckon Design System
Open playroom

Combobox

Allows the user to browse, search, and make a single selection from a large list of values.
Install
pnpm add @balance-web/combobox
Import usage
import {
  stateChangeTypesEnum,
  Combobox
} from '@balance-web/combobox';
  • Code
  • API

Alternatives

  • Autocomplete — Presents a filtered list only when the user has provided input. For extremely large datasets, where browsing the complete list would be inappropriate.
  • SelectInput — For small lists.

Usage

The Combobox is a controlled component. You "own" the state, which is managed by providing handlers to the component.

NOTE: All handlers must be memoized with React.useCallback() for performance.

NOTE: Pass the window object to the environment prop in Storybook (or when using inside an iframe) to prevent interaction issues.

Basic

The following props are required:

  • inputValue — The input value
  • items — The array of items for the user to select from
  • onChange — Handle changes to the selected item
  • onInputChange — Handle changes to the input value
  • value — The selected item
Edit in Playroom

Clear

Optionally provide an onClear handler, allowing users to "clear" their selection.

NOTE: Like all handlers, onClear must be memoized with React.useCallback() for performance.

Edit in Playroom

Data shape

By default the Combobox assumes that items will take the following shape:

type Item = {
  label: string;
  value: string | number;
  disabled?: boolean;
};

However, if your items have a different shape, you can provide "transform" functions to let the Combobox know how to handle your data:

  • itemToDisabled
  • itemToLabel
  • itemToValue

NOTE: All "transform" functions must be memoized with React.useCallback() for performance.

Edit in Playroom

Appearance

For brevity, search and selection are not implemented in the "appearance" examples.

Disabled

When "disabled" the Combobox will not be interactive and take on a dim appearance.

Edit in Playroom

Invalid

When the parent Field has an "invalidMessage" the Combobox controls will take on a "critical" appearance.

Edit in Playroom

Size

The Combobox suppports a size property, which influences the input controls and the default item height. For dense interfaces where screen reale state is limited you may want to use the "small" size.

Edit in Playroom

Placeholder

The text that appears in the form control when it has no value set.

Edit in Playroom

Custom item

To display a custom item you can provide an itemRenderer to the combobox.

NOTE: Should be a pure function (no side-effects), declared outside of the component.

Edit in Playroom

Item height

Because the scroll menu is virtualized we need an itemHeight (in pixels) to safely render the list. You only need to provide an itemHeight when using a custom itemRenderer and the height of your items differs from the default item implementation.

Edit in Playroom

By default, the menu dialog will match the width of the input container. For situations where horizontal real estate is limited this might mean that menu items are clipped. Provide a menuWidth prop to resolve the issue, accomodating expected item label lengths.

Edit in Playroom

Async

The logic for filtering items typically lives on the server rather than the client because it’s impractical to send all possible items over the network. However, when prototyping in Playroom or working with smaller datasets, you may want to perform this filtering on the client instead.

The async examples simulate a server request using the simulateFetch utility. You should not use this in your application.

Filtering

When fetching data from the server, update the loadingState to keep users informed. While the request is being processed, the loading indicator will let users know that their input has been recognised and that something is happening.

<Combobox loadingState="loading" />

NOTE: When fetching from the server based on user input you should always implement a constraint technique, like debounce or throttle, to limit the amount of requests.

Edit in Playroom

Pagination

Paginated data is handled in the Combobox using "infinite scrolling", a technique for loading more results as the user nears the bottom of a scroll view.

To paginate results you must provide:

  • mode="paginated"
  • canLoadMore — signal that more content is available
  • onLoadMore — called when the user nears the bottom of the menu (if canLoadMore)
  • loadingState — must be kept in-sync to avoid duplicate calls

NOTE: Like all handlers, onLoadMore must be memoized with React.useCallback() for performance.

Edit in Playroom

Advanced

The Combobox is tailored for the most common usage—where possible, simplicity and reduced API surface-area is preferred. There are however features available should you need them.

Actions such as "Create new" can be shown in the footer using the footerItem prop. The footer item is just a normal item rendered differently (for accessibility reasons) so most of the behavior is left to the consumer.

Below is a sample of how to implement a "Create new" item in the footer.

Edit in Playroom

State changes

The Combobox implements Downshift under-the-hood. Both onChange and onInputChange will provide "next state" as their second argument. This state is a result of the respective events, and can be used to alter the behaviour of your component.

type ComboboxState = Partial<{
  highlightedIndex: number;
  inputValue: string;
  isOpen: boolean;
  selectedItem: Item | null;
}>;

In the example below we're checking whether the input value exactly matches the recently selected item. If this is the case, we reset the list of items so they're visible next time the menu is opened.

Edit in Playroom

State reducer

For granular control of the state changing process, you can provide your own reducer. When stateReducer is called it will receive the previous state and the actionAndChanges object. actionAndChanges contains the change type, which explains why the state is being changed. It also contains the changes proposed that should occur as a consequence of that change type.

NOTE: The stateReducer should be a pure function (no side-effects), it should be declared it outside of your component.

The TS types you'll need are re-exported from this package as UseCombobox*. While Balance prefers string literals, Downshift implements an Enum for the change "type", which is exposed as stateChangeTypesEnum.

In the example below we'll uppercase the input value, and return the new value along with the rest of the changes. For all other state change types, we return the default changes.

Edit in Playroom

Messages

You can customise the message displayed to users when no items are available by providing a getMessageText callback, which has the signature:

(status: 'error' | 'noResults', inputValue: string) => string;

You can define this function outside of your component, or implement React.useCallback() to memoize it. Prefer the former where possible.

NOTE: You must account for each status in your function definition.

Edit in Playroom

The environment prop

This prop is only useful if you're rendering the combobox within a different window context from where your JavaScript is running; for example, an iframe or a shadow-root.

Simply pass the window object to the environment.

<Combobox {...otherProps} environment={window} />
Copyright © 2024 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo