Dropdown - Components - Design System

#Overview

Dropdowns are used with Forms (Code).

Show codeHide code

export const DropdownFieldDemo = () => {
  const form = useForm<{ fruits: ISelectOption<string> | null }>();
  return (
    <form onSubmit={form.handleSubmit(() => {})}>
      <DropdownField
        form={form}
        name="fruits"
        label="Favourite Fruit"
        items={fruitOptions}
        options={{
          required: {
            value: true,
            message: "Please provide a value",
          },
        }}
      />
      <ButtonGroup>
        <Button onClick={() => form.reset()}>Reset value</Button>
        <Button variant="primary" type="submit">
          Send
        </Button>
      </ButtonGroup>
    </form>
  );
};

Name	Type	Default	Description
form *	`UseFormReturn<TFieldValues>`	-	The connected form that the form field is part of
items *	`Array<ISelectOption>`	-	The selectable items
name *	`TFieldName`	-	The name of the input being registered from the form
value *	`ISelectOption` \| `null` \| `undefined`	-	The value of the input field
clearable	`boolean`	-	If a selected item can be cleared again, default false
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
helpText	`ReactNode`	-	A help text that can be displayed below the dropdown field
hideHelpAndValidation	`boolean`	-	Hides the help text and validation message
labelOptionalAppendix	`ReactNode`	-	Marker inside the label, when the field is optional
labelRequiredAppendix	`ReactNode`	-	Marker inside the label, when the field is required
noWrap	`boolean`	-
onBlur	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback the field is blurred
onChange	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes
onMenuClose	`() => void`	-	Callback when the menu closes
onMenuOpen	`() => void`	-	Callback when the menu opens
onSelect	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes
options	`UseControllerProps<TFieldValues, TFieldName>["rules"]`	`{ required: { value: true, message: __("Required") } }`	The options that can be set for the registration of the field
placeholder	`string`	-	A hint for the expected value

#Interface ISelectOption

The interface ISelectOption<T> is used to define the items of the dropdown. It is generic typed and will receive the interface of your actual data definition. It has the following properties:

Name	Type	Default	Description
label *	`string`	-	A label as string, this is required for internal matching or search (AutocompleteDropdown)
value *	`T`	-	The value of the option
disabled	`boolean`	-	If the option is disabled
labelComponent	`ReactNode`	-	Optional JSX to render complex layout (e.g. with Icon)

#Customize option rendering

You can render custom JSX as option label, just use the optional prop labelComponent for that purpose.

import type { ISelectOption } from "@blocks/form";
import { FlagCh16Icon } from "@blocks/icons";

const items: ISelectOption[] = [
  {
    labelComponent: (
      <>
        <FlagCh16Icon noColor />
        &nbsp; Switzerland
      </>
    ),
    label: "Switzerland",
    value: "switzerland",
  },
  // ...
];

#Autocomplete Dropdown

A Dropdown that lets you search for items by keyboard input.

Show codeHide code

export const AutocompleteDropdownFieldDemo = () => {
  const form = useForm<{ fruits: ISelectOption<string> | null }>();
  const [result, setResult] = useState<ISelectOption<string> | null>(null);
  return (
    <>
      <form
        onSubmit={form.handleSubmit(() => {
          setResult(form.getValues().fruits);
        })}
      >
        <AutocompleteDropdownField
          clearable
          form={form}
          name="fruits"
          label="Favourite Fruit"
          items={fruitOptions}
          options={{
            required: {
              value: true,
              message: "Please provide a value",
            },
          }}
        />
        <ButtonGroup>
          <Button onClick={() => form.reset()}>Reset value</Button>
          <Button variant="primary" type="submit">
            Send
          </Button>
        </ButtonGroup>
      </form>
      {result && <div>{`Submitted: ${result.value}`}</div>}
    </>
  );
};

Name	Type	Default	Description
form *	`UseFormReturn<TFieldValues>`	-	The connected form that the form field is part of
items *	`Array<ISelectOption>`	-	The selectable items
name *	`TFieldName`	-	The name of the input being registered from the form
value *	`ISelectOption` \| `null`	-	The value of the input field
clearable	`boolean`	-	If a selected item can be cleared again, default false
createNewValueMessage	`string`	-	The label that is shown above the creatable option
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
helpText	`ReactNode`	-	A help text that can be displayed below the input field
hideHelpAndValidation	`boolean`	-	Hides the help text and validation message
itemToString	`(item: ISelectOption,null) => string`	`(item) => item?.label ?? ""`	Parse function to convert the selected into into a string to show inside the input field
label	`ReactNode`	-	The label of the input field
labelOptionalAppendix	`ReactNode`	-	Marker inside the label, when the field is optional
labelRequiredAppendix	`ReactNode`	-	Marker inside the label, when the field is required
noItemsMessage	`string`	-	The message that will show when there are no results left after filtering
noWrap	`boolean`	-
onBlur	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the input field is blurred
onChange	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes and when input changes
onCreateItem	`(inputValue: string) => Promise<ISelectOption \| undefined \| void>`	-	Async callback to create new items. An option for that is shown when the user types something that is not present as an item
onInputValueChange	`(inputValue: string) => Promise<void>`	-	An optional callback to filter items asynchronous - useful to fetch an API again
onMenuClose	`() => void`	-	Callback when the menu closes
onMenuOpen	`() => void`	-	Callback when the menu opens
onSelect	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes
options	`UseControllerProps<TFieldValues, TFieldName>["rules"]`	`{ required: { value: true, message: __("Required") } }`	The options that can be set for the registration of the field
placeholder	`string`	-	A hint for the expected value
ref	`Ref<HTMLButtonElement>`	-	Ref of the dropdown

#Lazy loading items

If you're using an <AutocompleteDropdown /> or <MultiselectDropdown />, then you can implement the callback onInputValueChange to filter/fetch items. This is useful for data sources that can't be fully loaded initially. So you can use this callback to fetch the items with a new API request. The callback will be called on every keystroke - so it is recommended to implement this with a debounce function to avoid too many requests.

#Multiselect Dropdown

A Dropdown that let you select multiple items and also search for them by keyboard input.

Show codeHide code

export const MultiSelectDropdownFieldDemo = () => {
  const form = useForm<{ fruits: ISelectOption[] }>();
  const [result, setResult] = useState<ISelectOption[] | null>(null);
  return (
    <>
      <form
        onSubmit={form.handleSubmit(() => {
          setResult(form.getValues().fruits);
        })}
      >
        <MultiSelectDropdownField
          form={form}
          name="fruits"
          label="Favourite Fruit"
          items={fruitOptions}
          options={{
            required: {
              value: true,
              message: "Please provide a value",
            },
          }}
        />
        <ButtonGroup>
          <Button onClick={() => form.reset()}>Reset value</Button>
          <Button variant="primary" type="submit">
            Send
          </Button>
        </ButtonGroup>
      </form>
      {result && (
        <div>{`Submitted: ${result.map((item) => item.value).join(", ")}`}</div>
      )}
    </>
  );
};

Name	Type	Default	Description
form *	`UseFormReturn<TFieldValues>`	-	The connected form that the form field is part of
items *	`Array<ISelectOption>`	-	The selectable items
name *	`TFieldName`	-	The name of the input being registered from the form
value *	`Array<ISelectOption>` \| `null`	-	The value of the mutli select dropdown
createNewValueMessage	`string`	-	The label that is shown above the creatable option
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
helpText	`ReactNode`	-	A help text that can be displayed below the input field
hideHelpAndValidation	`boolean`	-	Hides the help text and validation message
itemToString	`(item: ISelectOption,null) => string`	`(item) => item?.label ?? ""`	Parse function to convert the selected into into a string to show inside the input field
label	`ReactNode`	-	The label of the input field
labelOptionalAppendix	`ReactNode`	-	Marker inside the label, when the field is optional
labelRequiredAppendix	`ReactNode`	-	Marker inside the label, when the field is required
noItemsMessage	`string`	-	The message that will show when there are no results left after filtering
noOptionsMessage	`string`	-	The message that will show when all items have been selected
noWrap	`boolean`	-
onBlur	`ChangeEventHandler<HTMLMultiSelectDropdownElement>`	-	Callback the input field is blurred
onChange	`ChangeEventHandler<HTMLMultiSelectDropdownElement>`	-	Callback when the selected item changes and when input changes
onCreateItem	`(inputValue: string) => Promise<ISelectOption \| undefined \| void>`	-	Async callback to create new items. An option for that is shown when the user types something that is not present as an item
onInputValueChange	`(inputValue: string) => Promise<void>`	-	An optional callback to filter items asynchronous - useful to fetch an API again
options	`UseControllerProps<TFieldValues, TFieldName>["rules"]`	`{ required: { value: true, message: __("Required") } }`	The options that can be set for the registration of the field
placeholder	`string`	-	A hint for the expected value
ref	`Ref<HTMLButtonElement>`	-	the ref of the mutli select dropdown

#Outside of a form

#Dropdown

Name	Type	Default	Description	Controls
items *	`Array<ISelectOption>`	-	The selectable items	-
value *	`ISelectOption` \| `null` \| `undefined`	-	The value of the input field	-
clearable	`boolean`	-	If a selected item can be cleared again, default false
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
onBlur	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback the field is blurred	-
onChange	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes	-
onMenuClose	`() => void`	-	Callback when the menu closes	-
onMenuOpen	`() => void`	-	Callback when the menu opens	-
onSelect	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes	-
placeholder	`string`	-	A hint for the expected value

#Autocomplete Dropdown

Name	Type	Default	Description	Controls
items *	`Array<ISelectOption>`	-	The selectable items	-
value *	`ISelectOption` \| `null`	-	The value of the input field	-
clearable	`boolean`	-	If a selected item can be cleared again, default false
createNewValueMessage	`string`	-	The label that is shown above the creatable option
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
itemToString	`(item: ISelectOption,null) => string`	`(item) => item?.label ?? ""`	Parse function to convert the selected into into a string to show inside the input field	-
noItemsMessage	`string`	-	The message that will show when there are no results left after filtering
onBlur	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the input field is blurred	-
onChange	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes and when input changes	-
onCreateItem	`(inputValue: string) => Promise<ISelectOption \| undefined \| void>`	-	Async callback to create new items. An option for that is shown when the user types something that is not present as an item	-
onInputValueChange	`(inputValue: string) => Promise<void>`	-	An optional callback to filter items asynchronous - useful to fetch an API again	-
onMenuClose	`() => void`	-	Callback when the menu closes	-
onMenuOpen	`() => void`	-	Callback when the menu opens	-
onSelect	`ChangeEventHandler<HTMLDropdownElement>`	-	Callback when the selected item changes	-
placeholder	`string`	-	A hint for the expected value
ref	`Ref<HTMLButtonElement>`	-	Ref of the dropdown	-

#Multiselect Dropdown

Name	Type	Default	Description	Controls
items *	`Array<ISelectOption>`	-	The selectable items	-
value *	`Array<ISelectOption>` \| `null`	-	The value of the mutli select dropdown	-
createNewValueMessage	`string`	-	The label that is shown above the creatable option
disabled	`boolean`	-	If true, the input field is disabled
hasError	`boolean`	-	If true, turns the border red
itemToString	`(item: ISelectOption,null) => string`	`(item) => item?.label ?? ""`	Parse function to convert the selected into into a string to show inside the input field	-
noItemsMessage	`string`	-	The message that will show when there are no results left after filtering
noOptionsMessage	`string`	-	The message that will show when all items have been selected
onBlur	`ChangeEventHandler<HTMLMultiSelectDropdownElement>`	-	Callback the input field is blurred	-
onChange	`ChangeEventHandler<HTMLMultiSelectDropdownElement>`	-	Callback when the selected item changes and when input changes	-
onCreateItem	`(inputValue: string) => Promise<ISelectOption \| undefined \| void>`	-	Async callback to create new items. An option for that is shown when the user types something that is not present as an item	-
onInputValueChange	`(inputValue: string) => Promise<void>`	-	An optional callback to filter items asynchronous - useful to fetch an API again	-
placeholder	`string`	-	A hint for the expected value
ref	`Ref<HTMLButtonElement>`	-	the ref of the mutli select dropdown	-

#Colors

Token
CHEVRON#000d#fffb#000d#fffb
CHEVRON_DISABLED#0004#fff4#0004#fff4
CHEVRON_ERROR#000d#fffb#000d#fffb
CHEVRON_FILLED#000d#fffb#000d#fffb
FIELD_BACKGROUND#fff#111#fff#111
FIELD_BACKGROUND_DISABLED#0000#fff1#0000#fff1
FIELD_BACKGROUND_ERROR#fff#111#fff#111
FIELD_BACKGROUND_FILLED#fff#111#fff#111
FIELD_BACKGROUND_FOCUS#fff#111#fff#111
FIELD_BORDER#bbb#fff4#bbb#fff4
FIELD_BORDER_DISABLED#0001#fff1#0001#fff1
FIELD_BORDER_ERROR#f75#f75#e02#f55
FIELD_BORDER_FILLED#bbb#fff4#bbb#fff4
FIELD_BORDER_FOCUS#555#fff#059#fff
HELP_TEXT#0009#fffb#0009#fffb
HELP_TEXT_DISABLED#0009#fffb#0009#fffb
HELP_TEXT_ERROR#c42#f75#e02#f44
HELP_TEXT_FILLED#0009#fffb#0009#fffb
HELP_TEXT_FOCUS#0009#fffb#0009#fffb
ICONAFTER_BACKGROUND#000d#fffb#000d#fffb
ICONAFTER_BACKGROUND_DISABLED#0004#fff4#0004#fff4
ICONAFTER_BACKGROUND_ERROR#000d#fffb#000d#fffb
ICONAFTER_BACKGROUND_FILLED#000d#fffb#000d#fffb
ICONAFTER_BACKGROUND_FOCUS#000d#fffb#000d#fffb
ICON_SHAPE#000d#fffb#000d#fffb
ICON_SHAPE_DISABLED#0004#fff4#0004#fff4
ICON_SHAPE_ERROR#000d#fffb#000d#fffb
ICON_SHAPE_FIELD_BACKGROUND_DISABLED#fff#111#fff#111
ICON_SHAPE_FILLED#000d#fffb#000d#fffb
LABEL_TEXT#0009#fffb#0009#fffb
LABEL_TEXT_DISABLED#0009#fffb#0009#fffb
LABEL_TEXT_ERROR#0009#fffb#0009#fffb
LABEL_TEXT_FILLED#0009#fffb#0009#fffb
LABEL_TEXT_FOCUS#0009#fffb#0009#fffb
VALUE_TEXT#0004#fff4#0004#fff4
VALUE_TEXT_DISABLED#0004#fff4#0004#fff4
VALUE_TEXT_ERROR#0004#fff4#0004#fff4
VALUE_TEXT_FILLED#000#fff#000#fff
VALUE_TEXT_FOCUS#0004#fff4#0004#fff4

#Overview

#Interface ISelectOption

#Customize option rendering

#Autocomplete Dropdown

#Lazy loading items

#Multiselect Dropdown

#Outside of a form

#Dropdown

#Autocomplete Dropdown

#Multiselect Dropdown

#Colors

About us