Gravity UI – UIKit

import {Select} from '@gravity-ui/uikit';

Компонент Select — это контрол, который предоставляет список вариантов для выбора.

`Options` (варианты)

Варианты для выбора.

Определение вариантов

Варианты можно определять в виде массива объектов или в качестве дочерних элементов компонента. Первый способ подходит для случаев, когда варианты требуют сложной подготовки и, возможно, запоминания. Второй способ удобен, когда вариантов немного и их настройка не требует сложных вычислений.

Одноуровневый список

Array of objects

Child nodes

<Select
  options={[
    {value: 'val_1', content: 'Value 1'},
    {value: 'val_2', content: 'Value 2'},
    {value: 'val_3', content: 'Value 3'},
    {value: 'val_4', content: 'Value 4'},
  ]}
/>
<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Группированный список

Array of objects

Child nodes

<Select
  options={[
    {
      label: 'Group 1',
      options: [
        {value: 'val_1', content: 'Value 1'},
        {value: 'val_2', content: 'Value 2'},
      ],
    },
    {
      label: 'Group 2',
      options: [
        {value: 'val_3', content: 'Value 3'},
        {value: 'val_4', content: 'Value 4'},
      ],
    },
  ]}
/>
<Select>
  <Select.OptionGroup label="Group 1">
    <Select.Option value="val_1" content="Value 1" />
    <Select.Option value="val_2" content="Value 2" />
  </Select.OptionGroup>
  <Select.OptionGroup label="Group 2">
    <Select.Option value="val_3" content="Value 3" />
    <Select.Option value="val_4" content="Value 4" />
  </Select.OptionGroup>
</Select>

Хранение данных в вариантах

С помощью свойства option.data можно определить и сохранить уникальные данные в каждом варианте. Это может быть полезно при необходимости обогащения данных с использованием обратного вызова onUpdate или, например, при отрисовке вариантов с помощью renderOption.

Выбор нескольких вариантов

Чтобы включить множественный выбор, используйте свойство multiple. Значение по умолчанию — false.

<Select multiple={true}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Счетчик

С помощью свойства hasCounter в компонент можно добавить счетчик выбранных вариантов.

<Select multiple={true} hasCounter={true}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Варианты фильтрации

Для активации секции фильтрации используйте свойство filterable. Значение по умолчанию — false.

<Select filterable={true}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Размер

Чтобы задать дефолтный размер контролов и вариантов, используйте свойство size. Размер по умолчанию — m.

<Select size="s" placeholder="S Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="m" placeholder="M Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="l" placeholder="L Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="xl" placeholder="XL Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>

Ширина контрола

По умолчанию ширина контрола растягивается, чтобы соответствовать ширине содержимого выбранных вариантов. Вы можете самостоятельно регулировать ширину с помощью свойства width:

'max' — растягивает ширину контрола на всю ширину родительского элемента.

number — применяет ширину в пикселях.

Default

Max

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select width="max">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select width={150}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Ширина всплывающего окна.

Ширину всплывающего окна можно изменять с помощью свойства popupWidth. Возможные значения:

'fit' — применяет ширину контрола.

number — применяет ширину в пикселях.

Особенности поведения по умолчанию:

Ширина всплывающего окна соответствует ширине самого широкого варианта, но не превышает 90vw. Это не применимо, если используется виртуализация.
Узкие варианты растягиваются до ширины контрола.

Non-virtualized list

A regular list when all the elements are in the dom tree at once.

Default

Fit

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>

Виртуализированный список

Для оптимального отображения большого количества вариантов в компоненте Selectпредусмотрен встроенный инструмент виртуализации списка. Виртуализация включается, когда количество вариантов превышает пороговое значение (по умолчанию 50). Пороговое значение можно изменить с помощью свойства virtualizationThreshold.

При включении виртуализации к элементу всплывающего окна применяются определенные ограничения:

Ширина всплывающего окна больше не изменяется в зависимости от длины самого длинного варианта.
Минимальная ширина всплывающего окна равна ширине контрола или 100px, если ширина контрола меньше 100px.

Default

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>

Расширенное использование

Существует множество способов настроить Select более тонко.

Рендеринг пользовательского контрола

Для создания пользовательского контрола используйте свойство renderControl. Обратите внимание, что для правильной работы контрола необходимо передать все аргументы в узел (как при использовании стандартной конфигурации).

<Select
  renderControl={({onClick, onKeyDown, ref}) => {
    return <button ref={ref} onClick={onClick} extraProps={{onKeyDown}}>Custom control</button>
  }}
>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

Отображение секции пользовательской фильтрации

Для отображения секции пользовательской фильтрации используйте свойство renderFilter и установите filterable в значение true. Обратите внимание, что для правильной работы фильтра необходимо передать все аргументы в узел (как при использовании стандартной конфигурации).

<Select
  placeholder="Custom filter"
  filterable={true}
  renderFilter={({onChange, onKeyDown, ref, value}) => {
    return (
      <div style={{display: 'flex', flexDirection: 'column'}}>
        <input
          ref={ref}
          value={value}
          size="1"
          onKeyDown={onKeyDown}
          onChange={(e) => onChange(e.target.value)}
        />
        <button>Do smth</button>
      </div>
    );
  }}
>
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>

Отображение пользовательских вариантов

Для отображения пользовательских вариантов используйте свойство renderOption:

<Select
  renderOption={(option) => {
    return (
      <div style={{color: option.data.color}}>
        {option.children}
      </div>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

Отображение выбранных пользовательских вариантов

Для отображения выбранных пользовательских вариантов используйте свойство renderOption:

<Select
  renderSelectedOption={(option) => {
    return (
      <div style={{color: option.data.color}}>
        {option.children}
      </div>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

Отображение вариантов с разной высотой

Варианты имеют фиксированную высоту, заданную в свойстве size. Если нужно отобразить варианты с разной высотой, используйте свойство option.data, которое будет содержать информацию о требуемой высоте варианта, а также getOptionHeight для установки этого значения.

<Select
  getOptionHeight={(option) => option.data.height}
>
  <Select.Option value="val_1" data={{height: 20}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{height: 40}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{height: 60}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{height: 80}}>Value 4</Select.Option>
</Select>

Отображение пользовательских всплывающих окон

Для отображения пользовательских всплывающих окон используйте свойство renderPopup.

<Select
  filterable
  placeholder="Custom popup"
  renderPopup={({renderList, renderFilter}) => {
    return (
      <React.Fragment>
        {renderFilter()}
        <div style={{width: "100%", height: "20px", backgroundColor: "tomato"}} />
        {renderList()}
      </React.Fragment>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

`Error` (ошибка)

Это состояние Select указывает на некорректный ввод данных пользователем. Для изменения внешнего представления Select примените свойство validationState, задав ему значение "invalid". Опционально можно задать текст сообщения об ошибке через свойство errorMessage. По умолчанию текст сообщения выводится вне компонента. Место вывода сообщения можно изменить с помощью свойства errorPlacement.

Error message

<Select placeholder="Placeholder" errorMessage="Error message" validationState="invalid" />
<Select placeholder="Placeholder" errorPlacement="inside" errorMessage="Error message" validationState="invalid" />

Свойства

Имя	Описание	Тип	Значение по умолчанию
className	Имя класса контрола.	`string`
defaultValue	Значения по умолчанию для выбранных вариантов в случае использования неуправляемого состояния.	`string[]`
disabled	Указывает на то, что пользователь не может взаимодействовать с контролом.	`boolean`	`false`
filterable	Указывает на то, что всплывающее окно выбора содержит секцию фильтрации.	`boolean`	`false`
filterOption	Используется для сравнения варианта со значением фильтра.	`function`
filterPlaceholder	Текст-заглушка по умолчанию для поля ввода фильтра.	`string`
getOptionHeight	Используется для задания высоты пользовательских вариантов.	`function`
getOptionGroupHeight	Используется для задания высоты группы пользовательских вариантов.	`function`
hasClear	Позволяет отображать иконку для очистки выбранных вариантов.	`boolean`	`false`
id	HTML-атрибут `id`.	`string`
label	Лейбл контрола.	`string`
loading	Добавляет элемент загрузки в конец списка вариантов. Работает как постоянный индикатор загрузки, пока список вариантов пуст.	`boolean`
multiple	Указывает на наличие возможности выбора несколько вариантов в списке.	`boolean`	`false`
name	Имя контрола.	`string`
onBlur	Обработчик, который вызывается, когда элемент теряет фокус.	`function`
filter	Контролируемое значение фильтра.	`string`	`''`
onFilterChange	Срабатывает при каждом изменении фильтра.	`function`
onFocus	Обработчик, который вызывается, когда элемент получает фокус.	`function`
onLoadMore	Срабатывает, когда индикатор загрузки становится видимым.	`function`
onOpenChange	Срабатывает при каждом изменении видимости всплывающего окна.	`function`
onUpdate	Срабатывает, когда пользователь подтверждает изменение значения `Select`.	`function`
options	Варианты для выбора.	`(SelectOption \| SelectOptionGroup)[]`
pin	Вид границ контрола.	`string`	`'round-round'`
placeholder	Текст-заглушка.	`string`
popupClassName	Имя класса (`className`) для всплывающего окна со списком вариантов.	`string`
popupPlacement	Размещение всплывающего окна.	`PopupPlacement` `Array<PopupPlacement>`	`['bottom-start', 'bottom-end', 'top-start', 'top-end']`
popupWidth	Ширина всплывающего окна.	`number \| 'fit' \| 'outfit'`	`'outfit'`
qa	Атрибут идентификатора для тестирования (`data-qa`).	`string`
renderControl	Используется для рендеринга пользовательского контрола.	`function`
renderEmptyOptions	Используется для рендеринга узла для пустого списка вариантов.	`function`
renderFilter	Используется для рендеринга секции пользовательской фильтрации.	`function`
renderOption	Используется для рендеринга пользовательских вариантов.	`function`
renderOptionGroup	Используется для рендеринга групп пользовательских вариантов.	`function`
renderSelectedOption	Используется для рендеринга выбранных пользователем вариантов.	`function`
renderPopup	Используется для рендеринга содержимого пользовательского всплывающего окна.	`function`
size	Размер контрола / вариантов.	`string`	`'m'`
value	Значения для выбранных вариантов.	`string[]`
view	Вид контрола.	`string`	`'normal'`
virtualizationThreshold	Порог количества вариантов, после которого включается виртуализация.	`number`	`50`
width	Ширина контрола	`string \| number`	`undefined`
errorMessage	Текст ошибки.	`string`
errorPlacement	Положение отображения ошибки.	`outside` `inside`	`outside`
validationState	Состояние валидации.	`"invalid"`
hasCounter	Показывает количество выбранных вариантов. Счетчик появляется только тогда, когда включен множественный выбор.	`boolean`

API CSS

Имя	Описание
`--g-select-focus-outline-color`	Цвет обводки при фокусе на элементе (по умолчанию отсутствует).

Select

§Options (варианты)

§Определение вариантов

§Одноуровневый список

§Группированный список

§Хранение данных в вариантах

§Выбор нескольких вариантов

§Счетчик

§Варианты фильтрации

§Размер

§Ширина контрола

Default

Max

In pixels

§Ширина всплывающего окна.

§Non-virtualized list

Default

Fit

In pixels

§Виртуализированный список

Default

In pixels

§Расширенное использование

§Рендеринг пользовательского контрола

§Отображение секции пользовательской фильтрации

§Отображение пользовательских вариантов

§Отображение выбранных пользовательских вариантов

§Отображение вариантов с разной высотой

§Отображение пользовательских всплывающих окон

§Error (ошибка)

§Свойства

§API CSS

`Options` (варианты)

Определение вариантов

Одноуровневый список

Группированный список

Хранение данных в вариантах

Выбор нескольких вариантов

Счетчик

Варианты фильтрации

Размер

Ширина контрола

Ширина всплывающего окна.

Non-virtualized list

Виртуализированный список

Расширенное использование

Рендеринг пользовательского контрола

Отображение секции пользовательской фильтрации

Отображение пользовательских вариантов

Отображение выбранных пользовательских вариантов

Отображение вариантов с разной высотой

Отображение пользовательских всплывающих окон

`Error` (ошибка)

Свойства

API CSS