@leafygreen-ui/combobox NPM

Combobox

npm (scoped)

View on MongoDB.design

Installation

Yarn

yarn add @leafygreen-ui/combobox

NPM

npm install @leafygreen-ui/combobox

Example

import { Combobox, ComboboxOption } from '@leafygreen-ui/combobox';

<Combobox
  label="Choose a fruit"
  description="Please pick one"
  placeholder="Select fruit"
>
  <ComboboxOption value="apple" />
  <ComboboxOption value="banana" />
  <ComboboxOption value="carrot" />
  <ComboboxOption value="dragonfruit" />
  <ComboboxGroup label="Peppers">
    <ComboboxOption value="cayenne" />
    <ComboboxOption value="habanero" />
    <ComboboxOption value="jalapeno" displayName="Jalapeño" />
  </ComboboxGroup>
</Combobox>;

Output HTML

<div>
  <div>
    <label id="combobox-label-1" for="combobox-input-1"> Choose a fruit </label>
    <p>Please pick one</p>
  </div>
  <div>
    <div
      role="combobox"
      aria-expanded="true"
      aria-controls="combobox-menu-1"
      aria-owns="combobox-menu-1"
      tabindex="-1"
      data-disabled="false"
      data-state="none"
    >
      <div>
        <input
          aria-label="Choose a fruit"
          aria-autocomplete="list"
          aria-controls="combobox-menu-1"
          aria-labelledby="combobox-label-1"
          id="combobox-input-1"
          placeholder="Select fruit"
          value=""
        />
      </div>
      <svg aria-label="Caret Down Icon">...</svg>
    </div>
  </div>
</div>

Properties

Prop	Type	Description	Default
`children`	`<ComboboxOption>`, `<ComboboxGroup>`	Define the Combobox Options by passing children
`multiselect`	`boolean`	Defines whether a user can select multiple options, or only a single option. When using TypeScript, `multiselect` affects the valid values of `initialValue`, `value`, and `onChange`	`false`
`initialValue`	`Array<string>`, `string`	The initial selection. Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`. Changing the `initialValue` after initial render will not change the selection.
`value`	`Array<string>`, `string`	The controlled value of the Combobox. Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`. Changing `value` after initial render will affect the selection. `value` will always take precedence over `initialValue` if both are provided.
`onChange`	`(Array<string>) => void`, `(string) => void`	A callback called when the selection changes. Callback recieves a single argument that is the new selection, either string, or string array
`overflow`	`'expand-y'`, `'expand-x'`, `'scroll-x'`	Defines the overflow behavior of a multiselect combobox. expand-y: Combobox has fixed width, and additional selections will cause the element to grow in the block direction. expand-x: Combobox has fixed height, and additional selections will cause the elemenet to grow in the inline direction. scroll-x: Combobox has fixed height and width, and additional selections will cause the element to be scrollable in the x (horizontal) direction.	`'expand-y'`
`label`	`string`	An accessible label for the input, rendered in a `<label>` to the DOM
`aria-label`	`string`	An accessible label for the input, used only for screen-readers
`description`	`React.ReactNode`	A description for the input
`placeholder`	`string`	A placeholder for the input element. Uses the native `placeholder` attribute.	'Select'
`disabled`	`boolean`	Disables all interaction with the component	false
`size`	`'default'`	Defines the visual size of the component	'default'
`darkMode`	`boolean`	Toggles dark mode	false
`state`	`'error'`, `'none'`	The error state of the component. Defines whether the error message is displayed.	'none'
`errorMessage`	`string`	The message shown below the input when `state` is `error`	'This input needs your attention'
`successMessage`	`string`	The message shown below the input when `state` is `valid`	'Success'
`onFilter`	`(value: string) => void`	A callback called when the search input changes. Recieves a single argument that is the current input value. Use this callback to set `searchState` and/or `filteredOptions` appropriately
`searchState`	`'unset'`, `'error'`, `'loading'`	The state of search results. Toggles search messages within the menu.	'unset'
`searchErrorMessage`	`string`	A message shown within the menu when `searchState` is `error`	'Could not get results!'
`searchLoadingMessage`	`string`	A message shown within the menu when `searchState` is `loading`	'Loading results...'
`searchEmptyMessage`	`string`	A message shown within the menu when there are no options passed in as children, or `filteredOptions` is an empty array	'No results found'
`clearable`	`boolean`	Defines whether the Clear button appears to the right of the input
`onClear`	`(e: MouseEvent) => void`	A callback fired when the Clear button is pressed. Fired after `onChange`, and before `onFilter`
`filteredOptions`	`Array<string>`, `null`	An array used to define which options are displayed. Do not remove Options from the JSX children, as this will affect the selected options
`chipTruncationLocation`	`'start'`, `'middle'`, `'end'`, `'none'`	Defines where the ellipses appear in a Chip when the length exceeds the `chipCharacterLimit`	'none'
`chipCharacterLimit`	`number`	Defined the character limit of a multiselect Chip before they start truncating. Note: the three ellipses dots are included in the character limit.	12
`className`	`string`	The className passed to the root element of the component.
`usePortal`	`boolean`	Will position Popover's children relative to its parent without using a Portal, if `usePortal` is set to false. NOTE: The parent element should be CSS position `relative`, `fixed`, or `absolute` if using this option.	`true`
`portalContainer`	`HTMLElement` \| `null`	Sets the container used for the popover's portal.
`scrollContainer`	`HTMLElement` \| `null`	If the popover portal has a scrollable ancestor other than the window, this prop allows passing a reference to that element to allow the portal to position properly.
`portalClassName`	`string`	Passes the given className to the popover's portal container if the default portal container is being used.
`popoverZIndex`	`number`	Sets the z-index CSS property for the popover.

ComboboxOption

Props

Prop	Type	Description
`value`	`string`	The internal value of the option. Used as the identifier in Combobox `initialValue`, `value` and `filteredOptions`. When undefined, this is set to `_.kebabCase(displayName)`
`displayName`	`string`	The display value of the option. Used as the rendered string within the menu and chips. When undefined, this is set to `value`
`glyph`	`<Icon/>`	The icon to display to the left of the option in the menu.
`className`	`string`	The className passed to the root element of the component.
`description`	`string`	Optional descriptive text under the displayName.
`onClick`	`(event: React.SyntheticEvent<HTMLLIElement, Event>, value: string) => void`	Callback fired when an option is clicked. Returns the event and the option value.

ComboboxGroup

Props

Prop	Type	Description
`label`	`string`	Label for the group of options
`children`	`<ComboboxOption>`	Options in the group
`className`	`string`	The className passed to the root element of the component.