Skip to main content

Options

Set of selectable options, displayed either as radio buttons, check-boxes, or drop-downs.

Props​

Option type is defined as follows:

  • [OPTIONAL] value (string): Option value (HTML value attribute). Required when type is neither header nor divider.
  • [OPTIONAL] disabled (boolean): Whether the option can be selected.
  • [OPTIONAL] label (string): Option label. Required when type is not divider.
  • [OPTIONAL] modifiers (string): List of modifiers to apply to the option.
  • [OPTIONAL] type ("header" | "divider" | "option"): Option type. Determines how the option will be displayed.

Available props are:

  • options (Option[]): List of options to display in the component.
  • name (string): name HTML attribute to set to the element.
  • [OPTIONAL] id (string): id HTML attribute to set to the element.
  • [OPTIONAL] placeholder (string): Placeholder to display when no option is selected (select mode only).
  • [OPTIONAL] modifiers (string): List of modifiers to apply to the element. Defaults to "".
  • [OPTIONAL] helper (string): Element helper. Supports light markdown.
  • [OPTIONAL] label (string): Element label. Supports light markdown.
  • [OPTIONAL] select (boolean): Whether to display options as a select (=drop-down). Defaults to false.
  • [OPTIONAL] expanded (boolean): Whether to force drop-down displaying in select mode. Defaults to false.
  • [OPTIONAL] multiple (boolean): Whether user can select several options. Determines how the component will be displayed. false will display options as radio buttons, true will display them as check-boxes, and true along with select set to true will display a multi-choices drop-down. Defaults to false.
  • [OPTIONAL] selectPosition ("top" | "bottom"): Pass this prop if you want to force options list positionning in select mode.
  • [OPTIONAL] value (string | string[]): Initial value (pre-selected options). Updating this prop with a new value will replace the current value by the one passed. Defaults to [].
  • [OPTIONAL] disabled (boolean): When element is disabled, a special disabled modifier is automatically added, and all its user interactions are disabled. Defaults to false.

Events​

  • change (newValue: string | string[], event: InputEvent) => void: Triggered whenever selected options change.
  • focus (focusedValue: string, event: FocusEvent) => void: Triggered whenever a specific option is focused, or when the main drop-down input is focused (in select mode).

Behavior​

For a better UX and consistency, we uniformized some behaviors across the different displaying modes (radio buttons, check-boxes, drop-down), especially regarding accessibility.

  • Pressing Tab allows to navigate from / to the component, and NOT among its own options.
  • Pressing Left/Up/Right/Bottom arrow keys allows to navigate through sibling options.
  • Pressing Home/End/PageUp/PageDown keys allows to navigate directly to the first / last selectable options, respectively.
  • Pressing Space/Enter keys allows to check or uncheck options.
  • Pressing Escape key hides select list (in select mode).
  • Updating value to the options props will re-apply focus to the first selectable or selected option, if an option was being focused before the update.
  • The change event is NOT triggered again when the value prop is updated.

Syntax - as radio buttons, with label and helper​

<UIOptions
  id="my-id"
  modifiers="large"
  name="test"
  label="Label"
  helper="Helper"
  options={[
    { value: 'option1', label: 'Option 1'},
    { value: 'option2', label: 'Option 2'},
    { value: 'option3', label: 'Option 3', disabled: true},
    { value: 'option4', label: 'Option 4', modifiers: 'modifier1' },
  ]}
/>

Syntax - as check-boxes, with initial value​

<UIOptions
  id="my-id"
  modifiers="large"
  name="test"
  multiple
  value={['option1']}
  options={[
    { value: 'option1', label: 'Option 1'},
    { value: 'option2', label: 'Option 2'},
    { value: 'option3', label: 'Option 3', disabled: true},
    { value: 'option4', label: 'Option 4'},
  ]}
/>

Syntax - as drop-down​

<UIOptions
  name="test"
  select
  expanded
  selectPosition="top"
  onChange={onChange}
  onFocus={onFocus}
  options={[
    { type: 'header', label: 'Group'},
    { type: 'option', value: 'option2', label: 'Option 2'},
    { type: 'divider' },
    { type: 'option', value: 'option4', label: 'Option 4'},
  ]}
/>