@highlight-ui/select

Feature-rich select control.

Collects user information by displaying a list, triggered by click action, allowing single or multiple selection.

Features

Supports selection of one or multiple options
Asynchronous flow
- built-in search bar
- search term highlighted results
- optional search in sub labels
- dynamically generated options
- loader
Option groups
- split multiple options my line separator and title
Option types
- single-line
- colored
- multi-line
- avatar
Option metadata
- built with TS generics
Footer
- apply action
- cancel action
Creatable option
Support for i18n
Controlled component
Variants
- inline
- full-width
🆕 🧪 Early access features
- New search input
- New trigger

Installation

Using npm:

npm install @highlight-ui/select

Using yarn:

yarn add @highlight-ui/select

Using pnpm:

pnpm install @highlight-ui/select

Once the package is installed, you can import the library:

import { Select } from '@highlight-ui/select';

Usage

Single

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function SingleSelectExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      options={[
        { label: 'Genesis', value: '23095' },
        { label: 'Destinee', value: '26211' },
      ]}
    />
  );
}

Multiple

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function MultiSelectExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  return (
    <Select
      multiple
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      options={[
        { label: 'Genesis', value: '23095' },
        { label: 'Destinee', value: '26211' },
      ]}
    />
  );
}

🆕 🧪 Early access features

The following sections highlight new features that can be enabled via props.

Search input

When the content is open, a search input will be visible if the searchable prop is set to true and the number of options is equal or above the number as provided through the minOptionsToDisplaySearch prop.

By default enableNewSearchInput will be false. Below is a comparison of what it renders, based on its value.

`enableNewSearchInput`	Component	Comments
`false`	`DefaultSearchInput`	Wrapper with `role="search"` containing a `<label>` which groups an `<Icon>` and `<input>`
`true`	`SearchInput`	Uses the `<TextInput>` component with an `<Icon>` as prefix

Trigger

By default enableFlowTriggers will be false. Below is a comparison of what it renders, based on its value.

`enableFlowTriggers`	`multiple`	Component	Comments
`false`	`false`	`DefaultTrigger` or Custom `renderTrigger()`	`<button>` showing the selected option (by default) or a custom element
`false`	`true`	`DefaultSearchInput` or Custom `renderTrigger()`	`<button>` showing the selected options count and clear icon (by default) or a custom element
`true`	`false`	`InputTrigger`	`<InputContainer>` component with an `<IconButton>` as suffix, showing the selected option
`true`	`true`	`MultiInputTrigger`	`<InputContainer>` component with an `<IconButton>` as suffix, showing the selected options as `<SelectChip>`s and clear icon

Advanced usage

Asynchronous flow

This example focus on loading options asynchronously. In real-world example, in the onListVisibilityChange handler hardcoded options would be replaced by API call.

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

const initialOptions: SelectOption[] = [
  { label: 'Genesis', value: '23095' },
  { label: 'Destinee', value: '26211' },
  { label: 'Chyna', value: '86910' },
  { label: 'Alexie', value: '49249' },
  { label: 'Natalie', value: '18694' },
];

export default function AsyncExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  const [options, setOptions] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      searchable
      isLoading={isLoading}
      minOptionsToDisplaySearch={1}
      onListVisibilityChange={(visible) => {
        if (visible) {
          setIsLoading(true);
          // mocks API call. Should be replaced with network request
          setTimeout(() => {
            setOptions(initialOptions);
            setIsLoading(false);
          }, 3000);
        }
      }}
      options={options}
    />
  );
}

Option groups

Option groups provide a way to visually group multiple options. Groups are determined by specifying a group title in each option.

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function OptionGroupsExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      options={[
        { label: 'Genesis', value: '23095', group: 'One' },
        { label: 'Destinee', value: '26211', group: 'Two' },
      ]}
    />
  );
}

Option types

Four different option types are supported:

single-line
colored
multi-line
avatar

Option types are determined by specifying optionType prop. Additionally, each option type has its own props which are specified in each option.

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function OptionTypesExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      optionType="colored"
      options={[
        { label: 'Genesis', value: '23095', color: 'red' },
        { label: 'Destinee', value: '26211', color: 'green' },
      ]}
    />
  );
}

In addition to the label, value and group, these props are used to define option type:

Prop	Type	Option type	Description
`disabled`	`boolean`	all	Should the option be disabled or enabled
`metadata`	`ComponentMetadata`	all	Object used for testing. Contains testId and actionName
`subLabel`	`string`	multi-line and avatar	Smaller, descriptive text used below main label
`avatar`	`string`	avatar	URL used to fetch avatar image
`imageLoading`	`eager` or `lazy`	avatar	Specifies how browser will load avatar image

Creatable option

Select has a support for options dynamically created by user.

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function CreatableOptionExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  const [options, setOptions] = useState([
    {
      label: 'Genesis',
      value: '23095',
    },
  ]);
  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      creatableOptions={{
        createButtonProps: {
          label: 'Add',
          loading: false,
        },
        inputProps: {
          placeholder: 'Create a new one',
        },
        onCreate: (item) => {
          setOptions([...options, { label: item.value, value: item.value }]);
        },
      }}
      options={options}
    />
  );
}

⚠️ Submit footer cannot be used alongside creatable options.

CreatableOptionsProps

Prop	Type	Required	Default	Description
`createButtonProps.label`	`string`	Yes		Text used in the submit button
`createButtonProps.loading`	`boolean`	No	`false`	Defines if the submit button will be in loading state
`createButtonProps.metadata`	`ComponentMetadata`	No	`null`	Object used for testing. Contains testId and actionName
`inputProps.placeholder`	`string`	No	`null`	Placeholder used in search bar
`inputProps.metadata`	`ComponentMetadata`	No	`null`	Object used for testing. Contains testId and actionName
`onCreate`	`function(item: SelectOption): void`	Yes	`null`	Function called whenever new option is created

Submit footer

Select has a support for submit footer.It provides distinction between selected and submitted options. This means that changes in selected options can be discarded.

import React from 'react';
import { Select, SelectOption } from '@highlight-ui/select';

export default function SubmitFooterExample() {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  const [submittedOptions, setSubmittedOptions] = useState<SelectOption[]>([]);

  return (
    <Select
      triggerLabel="Pick a name"
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      multiple
      options={[
        { label: 'Genesis', value: '23095' },
        { label: 'Destinee', value: '26211' },
      ]}
      submitOptions={{
        onCancel: () => setSelectedOptions(submittedOptions),
        onSubmit: (options) => setSubmittedOptions(options),
      }}
    />
  );
}

⚠ Creatable options cannot be used alongside submit footer.

SubmitOptions

Prop	Type	Required	Default	Description
`submitOptions.onSubmit`	`function(options: SelectOption[]): void`	Yes		Function called whenever the submit button is pressed
`submitOptions.onCancel`	`function(): void`	Yes		Function called whenever the cancel button is pressed
`submitOptions.submitLabel`	`string`	No	'Apply'	Label used in the submit button
`submitOptions.cancelLabel`	`string`	No	'Cancel'	Label used in the cancel button

Props 📜

ℹ️ Whenever SelectOption is used, there is an option to extend this interface and provide your own metadata.

Prop	Type	Required	Default	Description
`options`	`SelectOption[]`	Yes		List of objects
`onSelect`	`function(values: SelectOption[]): void`	Yes		Gets called each time an option is selected
`selectedOptions`	`SelectOption[]`	Yes		List of selected options
`className`	`string`	No	`null`	Class name to apply to the element
`listClassName`	`string`	No	`null`	Class name to apply to the List element
`closeOnSelect`	`boolean`	No	`false`	Should the options list disappear by each selection?
`disabled`	`boolean`	No	`false`	Should trigger be enabled or disabled
`selectAllLabel`	`string`	No	'Select all'	Label for `Select all` functionality when `multiple` prop is `true`
`metadata`	`ComponentMetadata`	No	`null`	Object used for testing. Contains testId and actionName
`onSearchChange`	`function(search: string): void`	No	`null`	Gets called whenever text is typed in search bar
`onListVisibilityChange`	`function(visible: boolean): void`	No	`null`	Gets called whenever the visibility of the select's list has changed
`emptyStateLabel`	`string`	No	'Nothing to display'	Label for displaying the empty state of the Select list
`renderEmptyState`	`function(props: SelectEmptyStateProps): ReactNode`	No	`null`	Function to return custom empty options list message
`renderTrigger`	`function(props: SelectTriggerProps & ref: RefCallback): ReactNode`	No	`null`	Function to return a custom trigger
`optionType`	`single-line or colored or multi-line or avatar`	No	'single-line'	String specifying the option type that should be rendered.
`variant`	`inline or full-width`	No	'inline'	`inline` when used outside forms and `full-width` when used inside forms
`searchable`	`boolean`	No	`true`	Determines whether or not a search input should be rendered in the select list
`searchAutofocus`	`boolean`	No	`true`	Whether or not the search field should get the focus automatically each time the list opens up
`searchInitialValue`	`string`	No	`null`	Initial search field value
`searchNoResultsLabel`	`string`	No	'No results for'	No search results message
`searchPlaceholder`	`string`	No	'Search'	No search results message
`minOptionsToDisplaySearch`	`number`	No	8	If Select is searchable search input will render if the number of options is more or equal to this number.
`triggerLabel`	`string`	No	`null`	Label being shown by default on the trigger button
`outline`	`default or warning or error`	No	'default'	String specifying the outline that should be rendered
`autoFocus`	`boolean`	No	`false`	Automatically focus the Select's trigger on mount
`triggerId`	`string`	No	`null`	HTML id attribute asssigned to trigger component
`creatableOptions`	`CreatableOptionsProps`	No	`null`	Options used for creatable option feature
`isClearable`	`boolean`	No	`false`	Defines wether to render the clearing x button
`highlightedText`	`string`	No	`null`	Highlights this text in the options list only when the Select is not searchable.
`isLoading`	`boolean`	No	`false`	Display the loading state of the list
`submitOptions`	`SubmitOptions`	No	`null`	Options used for the submit button
`enableFlowTriggers`	`boolean`	No	`false`	Allow toggling between original and new trigger
`enableNewSearchInput`	`boolean`	No	`false`	Allow toggling between original and new search input
`limitTwoRows`	`boolean`	No	`true`	Limit selected chips to only display two rows. Only applicable to multi-select.
`enableSubLabelSearch`	`boolean`	No	`false`	Search in subLabel text when `optionType` is `multi-line`

SelectEmptyStateProps

Prop	Type	Required	Default	Description
`label`	`string`	No	`null`	Label shown in the empty

Accessibility ♿️

Select tries to mimic native HTML select a11y features as best as possible.

This is well-known to be a notoriously hard job There are some smaller deviation to native select's behaviour:

Keyboard navigation
- using keyboard letters won't focus on list options

Testing

This example serves as starting point on how you can use Select component as part of your tests.

Some of the props are already defined in the SelectWrapper since they are mandatory but they can be overriden by sending props to the renderSelectWrapper function.

import React, { useState } from 'react';
import { render } from '@testing-library/react';
import { Select, SelectOption } from '@highlight-ui/select';

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
type SelectWrapperProps = Optional<
  SelectProps<SelectOption>,
  'selectedOptions' | 'onSelect' | 'options'
>;

function SelectWrapper(props: SelectWrapperProps) {
  const [selectedOptions, setSelectedOptions] = useState<SelectOption[]>([]);
  return (
    <Select
      selectedOptions={selectedOptions}
      onSelect={setSelectedOptions}
      options={[
        { label: 'Genesis', value: '23095', color: 'red' },
        { label: 'Destinee', value: '26211', color: 'green' },
      ]}
      {...props}
    />
  );
}

describe('SelectTest', () => {
  const renderSelectWrapper = (props: SelectWrapperProps) => {
    return render(<SelectWrapper {...props} />);
  };

  it('test description', () => {
    renderSelectWrapper({});
    // write your expect here
  });
});

Place in design system 💻

Select component's flexibility is used to implement a number of different components:

For picking a color from a color palette, color-picker should be used.

For picking unselectable menu item which will open URL or call custom callback, look at the dropdown-menu

Contributing 🖌️

Please visit personio.design.

If you're interested in contributing, please visit our contribution page.