SelectInput

import { SelectInput } from '@uhg-abyss/mobile';

label

hintText

isDisabled

isRequired

helpContent

() => {
  const form = useForm();

  return (
    <FormProvider state={form}>
      <SelectInput
        model="select-input-sandbox"
        label="Menu"
        options={[
          {
            title: 'Title 1',
            items: [
              { label: 'item 1', value: 'item11', isDisabled: false },
              { label: 'item 2', value: 'item12', isDisabled: true },
              { label: 'item 3', value: 'item13', isDisabled: false },
            ],
          },
          {
            title: 'Title 2',
            items: [
              { label: 'item 1', value: 'item21', isDisabled: false },
              { label: 'item 2', value: 'item22', isDisabled: false },
              { label: 'item 3', value: 'item23', isDisabled: false },
            ],
          },
        ]}
      />
    </FormProvider>
  );
};

Usage

Use the options prop to supply the options that can be selected. options is an array of objects, where each object should have two properties:

label, a string which is how the option will be displayed in the list
value, a string which is the unique identifier for the option

Sections can also be specified, in which case the section object should have title and items properties instead of label and value (See Titles for more details).

options = {
  [
    { label: 'Item 1', value: 'item1' },
    { label: 'Item 2', value: 'item2', isDisabled: true },
    { label: 'Item 3', value: 'item3' },
    { label: 'Item 4', value: 'item4' },
    { label: 'Item 5', value: 'item5' },
  ]
}

useForm (recommended)

Use the useForm hook to manage the state of the select input. The model prop should be set to a unique string that identifies the form field.

useState

Using the useState hook gets values from the component state.

Titles

To create sections in the list, pass objects into the options array that have the title and items properties. title specifies the name of the title, which will be bolded and not selectable, items should contain the options within that section (with the same label/value format as normal).

Label

Use the label prop to display a label above the input menu.

Required

Form Compatibility

useState

useForm

Use the isRequired prop to display an asterisk next to the label when using useState.

Hint Text

Use the hintText prop to display text below the label.

Help Content

Use the helpContent prop to display a help icon in the top right of the container, which will display the provided content in a modal screen when pressed.

Error Message (useState)

Form Compatibility

useState

useForm

Use the errorMessage prop to display a custom error message below the menu when using useState.

Success Message

Form Compatibility

useState

useForm

Use the successMessage prop to display a custom success message below the menu.

Disabled

Set the isDisabled prop to true to disable the select list input field so users cannot select a value.

Disable Option Items

Disable an individual option item by setting the isDisabled key to true within the object.

Multi Select

Use the asMulti prop to enable multi-select mode. When enabled, the component renders checkboxes and supports selecting multiple values. The value prop becomes a string[] and onChange passes a string[].

Select All

When using asMulti, set the selectAll prop to true to make a "Select All" option visible at the top of the dropdown. When selected, all options will be selected. When deselected, all options will be deselected.

Searchable

Use the isSearchable prop to display a search bar inside the menu for filtering options. This works for both single and multi-select modes.

Use the menuHeading prop to set a custom title for the menu. If not provided, the label value is used as the heading.

Note

The modalHeading prop is deprecated. Use menuHeading instead.

Use the menuContentTop and menuContentBottom props to render custom content within the menu. menuContentTop renders above the search bar, and menuContentBottom renders below it.

Fuse.js

Search bar filtering uses the Fuse.js library to fuzzy filter results. The default configuration is:

{
  keys: ['label', 'items.label'],
  includeMatches: true,
  findAllMatches: true,
  threshold: 0,
  ignoreLocation: true,
  minMatchCharLength: searchText.length,
}

Custom Fuse Configurations

You can customize the fuse filter by following the documentation on Fuse and passing your configurations into the fuseConfigs prop. To get the filtered list back, be sure includeMatches is always set to true.

Custom Filtering

Use the customFilter prop to override the Fuse.js filtering. The function receives the search text and the full list of options, and should return the filtered results. Any type-ahead highlight styles will not be applied when a custom filtering function is being used.

Migration from SelectInputMulti

Deprecation Notice

SelectInputMulti is deprecated. Use SelectInput with the asMulti prop instead.

SelectInputMulti	SelectInput
`<SelectInputMulti />`	`<SelectInput asMulti />`
`value: string[]`	`value: string[]` (when `asMulti`)
`onChange: (value: string[]) => void`	`onChange: (value: string[]) => void` (when `asMulti`)
`selectAll`	`selectAll` (when `asMulti`)
`isSearchable`	`isSearchable`
`fuseConfigs`	`fuseConfigs`
`customFilter`	`customFilter`
`modalHeading`	`menuHeading` (renamed, `modalHeading` deprecated)

SelectInput Props

Name	Type	Default	Required	Description
asMulti	false \| true \| undefined	false	-	Enables multi-select mode with checkboxes
customFilter	(searchText: string, list: SelectInputOption[]) => any[] \| undefined	-	-	Custom function used for search
errorMessage	string \| undefined	-	-	Error message to be displayed below the select input field
fuseConfigs	Fuse.IFuseOptions<any> \| undefined	-	-	Configs for Fuse
helpButtonAccessibilityLabel	string \| undefined	-	-	Set the accessibility label for the help button
helpContent	React.ReactNode \| undefined	-	-	When defined, displays a help icon that can be tapped to view the provided content in a modal screen
hintText	string \| undefined	-	-	Text displayed below the select input field
isDisabled	boolean \| undefined	false	-	Flag to enable/disable the select list. If true, the select list will be disabled
isRequired	boolean \| undefined	false	-	Flag to add an asterisk next to the label, indicating that the field is required. This is independent of form validation and is only for visual purposes.
isSearchable	boolean \| undefined	false	-	Flag to enable/disable the select list search/filter feature
label	string \| undefined	-	-	Select list label
menuContentBottom	React.ReactElement \| undefined	-	-	Content to render within the menu. Renders below the search bar if isSearchable is true.
menuContentTop	React.ReactElement \| undefined	-	-	Content to render within the menu. Renders above the search bar if isSearchable is true.
menuHeading	string \| undefined	-	-	Heading of the input menu
modalHeading	string \| undefined	-	-	Heading of the input modal
model	never \| string \| undefined	-	-	model is only used when the input is bound to a form via useForm. Model name used to bind the input to the form state. Only used inside a FormProvider.
onChange	(value?: string) => void \| (value: string[]) => void \| undefined	-	-	Callback fired every time the value changes
options	SelectInputOption[] \| undefined	'[]'	-	List of options selectable in the select list input. { label: string, value: string }
placeholder	string \| undefined	-	-	The rendered string when no option is selected
selectAll	never \| boolean \| undefined	false	-	Toggles the Select All option
showHint	boolean \| undefined	-	-	Shows the hint text
showOptionalLabel	boolean \| undefined	-	-	Flag to display 'optional' next to the label
successMessage	string \| undefined	-	-	Success message to be displayed below the select input field
validations	Validations \| undefined	-	-	Set rules for the input to be valid. Valid in both useState and useForm modes. Set rules for the input to be valid.
value	string \| string \| string[] \| string[] \| undefined	'[]'	-	Option value selected in the select list input Option value(s) selected in the select list input Option values selected in the select list input

SelectInput Classes

Extends Abyss - BottomSheet Classes

Class Name	Description
abyss-select-input-root	Root element
abyss-select-input-header	Header element
abyss-select-input-label	Label element
abyss-select-input-hint-text	Input hint text
abyss-select-input-help-button	Help button
abyss-select-input-help-modal	Help modal
abyss-select-input-open-icon	Menu open icon
abyss-select-input-modal	Deprecated. Styled via BottomSheet. Will be removed in V3.
abyss-select-input-menu-list	Menu list
abyss-select-input-message	Message element
abyss-select-input-container	Interactive input container
abyss-select-input-close-icon	Deprecated. Styled via BottomSheet close icon. Will be removed in V3.
abyss-input-help-icon	Help icon element
abyss-input-help-modal-footer	Help modal footer
abyss-input-help-modal-close-button	Help modal close button
abyss-select-input-text-container	Text container
abyss-select-input-text	Select input text
abyss-select-input-placeholder	Placeholder text
abyss-select-input-menu-container	Menu container
abyss-select-input-menu-list-title	Menu list section title
abyss-select-input-menu-item-container	Menu item container
abyss-select-input-menu-item	Menu item
abyss-select-input-menu-item-text	Menu item text
abyss-select-input-menu-item-radio	Menu item radio
abyss-select-input-menu-item-checkbox	Menu item checkbox
abyss-select-input-menu-item-select-all-checkbox	Select all checkbox
abyss-select-input-footer	Deprecated. Styled via BottomSheet footer container. Will be removed in V3.
abyss-select-input-footer-button	Menu footer submit button
abyss-select-input-search-input	Search input inside the menu
abyss-input-message-icon	Message icon
abyss-input-message-text	Message text

SelectInput Translations

Translation Key	Value
help	Help
close	Close
error	Error
success	Success
checked	Checked
notChecked	Not Checked
mixed	Mixed
SelectInput.placeholder	Select an Option

SelectInput Tokens

Search tokens

Token Name	Value
input-header.color.text.label	#4B4D4F
input-header.color.text.hint	#4B4D4F
input-header.color.icon.help.rest	#196ECF
input-header.color.icon.help.active	#004BA0
input-message.color.text.error	#990000
input-message.color.text.success	#007000
input-message.color.icon.error	#990000
input-message.color.icon.success	#007000
input-field.color.surface.default	#FFFFFF
input-field.color.surface.disabled	#F3F3F3
input-field.color.text.input	#4B4D4F
input-field.color.border.rest.default	#4B4D4F
input-field.color.border.rest.error	#990000
input-field.color.border.rest.success	#007000
input-field.color.border.active.default	#196ECF
input-field.color.border.active.error	#990000
input-field.color.border.active.success	#007000
input-field.color.icon.utility.rest	#4B4D4F
input-field.color.icon.utility.disabled	#929496
input-field.color.icon.utility.active	#323334
input-field.border-radius.all.container	4
input-field.border-width.all.container.rest	1
input-field.border-width.all.container.active	3
input-header.sizing.all.icon.help	24
input-message.sizing.all.icon.leading	20
input-field.sizing.icon.all.utility	20
input-field.sizing.icon.all.picker	20
input-container.spacing.gap.vertical.container	8
input-header.spacing.gap.horizontal.container	12
input-header.spacing.gap.horizontal.label	4
input-header.spacing.gap.vertical.content	4
input-message.spacing.gap.horizontal.container	4
input-field.spacing.padding.all.field	12
input-field.spacing.gap.horizontal.field	12
input-field.spacing.gap.horizontal.input-indicator	2
input-field.spacing.gap.horizontal.prefix-input	2
input-field.box-shadow.container.active	Shadow Color: $core.color.brand.60 Shadow Offset: Width: 0 Height: 0 Shadow Opacity: 1 Shadow Radius: 4
input-field.box-shadow.container.error	Shadow Color: $core.color.red.120 Shadow Offset: Width: 0 Height: 0 Shadow Opacity: 1 Shadow Radius: 4
input-field.box-shadow.container.success	Shadow Color: $core.color.green.100 Shadow Offset: Width: 0 Height: 0 Shadow Opacity: 1 Shadow Radius: 4

Usage

useForm (recommended)

useState

Titles

Label

Required

Hint Text

Help Content

Error Message (useState)

Success Message

Disabled

Disable Option Items

Multi Select

Select All

Searchable

Menu Heading

Menu Content

Fuse.js

Custom Fuse Configurations

Custom Filtering

Migration from SelectInputMulti

SelectInput Props

SelectInput Classes

SelectInput Translations

SelectInput Tokens

Usage​

useForm (recommended)​

useState​

Titles​

Label​

Required​

Hint Text​

Help Content​

Error Message (useState)​

Success Message​

Disabled​

Disable Option Items​

Multi Select​

Select All​

Searchable​

Menu Heading​

Menu Content​

Fuse.js​

Custom Fuse Configurations​

Custom Filtering​

Migration from SelectInputMulti​

SelectInput Props​

SelectInput Classes​

SelectInput Translations

SelectInput Tokens​

Usage

useForm (recommended)

useState

Titles

Label

Required

Hint Text

Help Content

Error Message (useState)

Success Message

Disabled

Disable Option Items

Multi Select

Select All

Searchable

Menu Heading

Menu Content

Fuse.js

Custom Fuse Configurations

Custom Filtering

Migration from SelectInputMulti

SelectInput Props

SelectInput Classes

SelectInput Tokens