Combobox

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. | | | renderMode | 'inline' | 'portal' | 'top-layer' | Options to render the popover element * [deprecated] 'inline' will render the popover element inline in the DOM where it's written * [deprecated] 'portal' will render the popover element in a new div appended to the body. Alternatively, can be portaled into a provided portalContainer * 'top-layer' will render the popover element in the top layer | 'top-layer' | 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 | Default | | ------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | 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 | Default | | ----------- | ------------------ | ---------------------------------------------------------- | ------- | | 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. | |