@highlight-ui/select

v10.6.5

Published

9 days ago

Select component for the Highlight UI library

Downloads

6,601

0High
0Medium
0Low

kbpersonio

ante.zebic

mislav_lukac_personio_ext

@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.

Trigger

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

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:

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

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.

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@highlight-ui/select

Features

Installation

Usage

Single

Multiple

🆕 🧪 Early access features

Search input

Trigger

Advanced usage

Asynchronous flow

Option groups

Option types

Creatable option

CreatableOptionsProps

Submit footer

SubmitOptions

Props 📜

SelectEmptyStateProps

Accessibility ♿️

Testing

Place in design system 💻

Contributing 🖌️