Forma 36 - Select

Import

import { Select } from '@contentful/f36-components';
// or
import { Select } from '@contentful/f36-forms';

Examples

Using as a controlled select

Controlled components in React are those in which form data is handled by the component’s state.

For using the Select as a controlled component, you need to:

Pass one of the options as the value property, with this property it will already be a controlled component;
Pass a onChange handler, so you can use it to update the value of value;


function SelectControlledExample() {
  const [selectValue, setSelectValue] = useState('optionOne');
  const handleOnChange = (event) => setSelectValue(event.target.value);

  return (
    <Select
      id="optionSelect-controlled"
      name="optionSelect-controlled"
      value={selectValue}
      onChange={handleOnChange}
    >
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}function SelectControlledExample() {
  const [selectValue, setSelectValue] = useState('optionOne');
  const handleOnChange = (event) => setSelectValue(event.target.value);

  return (
    <Select
      id="optionSelect-controlled"
      name="optionSelect-controlled"
      value={selectValue}
      onChange={handleOnChange}
    >
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}
Open in Playground

Using as an uncontrolled select

Uncontrolled components are those for which the form data is handled by the DOM itself. “Uncontrolled” refers to the fact that these components are not controlled by React state.

You can use the Select as an uncontrolled component, for that you can:

Set the defaultValue property, it will ensure that the select value can be altered normally.
Don't set the value property as it will make the select controlled.


function SelectUncontrolledExample() {
  return (
    <Select
      id="optionSelect-uncontrolled"
      name="optionSelect-uncontrolled"
      defaultValue="optionOne"
    >
      <Select.Option value="optionOne">Option 1</Select.Option>{' '}
      {/* This option would be selected by default */}
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}function SelectUncontrolledExample() {
  return (
    <Select
      id="optionSelect-uncontrolled"
      name="optionSelect-uncontrolled"
      defaultValue="optionOne"
    >
      <Select.Option value="optionOne">Option 1</Select.Option>{' '}
      {/* This option would be selected by default */}
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}
Open in Playground

Select with label

In order to provide the best experience for your users consider using label that we provide for you in the FormControl


function SelectWithLabelExample() {
  return (
    <FormControl>
      <FormControl.Label>Label for select</FormControl.Label>
      <Select id="optionSelect" name="optionSelect">
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Long Option 2</Select.Option>
      </Select>
      <FormControl.HelpText>Select one of the options</FormControl.HelpText>
    </FormControl>
  );
}function SelectWithLabelExample() {
  return (
    <FormControl>
      <FormControl.Label>Label for select</FormControl.Label>
      <Select id="optionSelect" name="optionSelect">
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Long Option 2</Select.Option>
      </Select>
      <FormControl.HelpText>Select one of the options</FormControl.HelpText>
    </FormControl>
  );
}
Open in Playground

Select with validation

There might be cases where you would need to include the help text or validation message into your form. Read more about those elements in FormControl documentation


function SelectWithValidationExample() {
  return (
    <FormControl>
      <FormControl.Label>Label for select</FormControl.Label>
      <Select id="optionSelect" name="optionSelect">
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Long Option 2</Select.Option>
      </Select>
      <FormControl.HelpText>Help text for your select</FormControl.HelpText>
      <FormControl.ValidationMessage>
        Validation message
      </FormControl.ValidationMessage>
    </FormControl>
  );
}function SelectWithValidationExample() {
  return (
    <FormControl>
      <FormControl.Label>Label for select</FormControl.Label>
      <Select id="optionSelect" name="optionSelect">
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Long Option 2</Select.Option>
      </Select>
      <FormControl.HelpText>Help text for your select</FormControl.HelpText>
      <FormControl.ValidationMessage>
        Validation message
      </FormControl.ValidationMessage>
    </FormControl>
  );
}
Open in Playground

Select available sizes


function SelectSizes() {
  return (
    <Stack>
      <SectionHeading>Size Medium</SectionHeading>
      <Select
        id="optionSelect-medium"
        name="optionSelect-medium"
        defaultValue="optionTwo"
      >
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Option 2</Select.Option>
        <Select.Option value="optionThree" isDisabled>
          Disabled option
        </Select.Option>
      </Select>
      <SectionHeading>Size Small</SectionHeading>
      <Select
        id="optionSelect-small"
        name="optionSelect-small"
        size="small"
        defaultValue="optionTwo"
      >
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Option 2</Select.Option>
        <Select.Option value="optionThree" isDisabled>
          Disabled option
        </Select.Option>
      </Select>
    </Stack>
  );
}function SelectSizes() {
  return (
    <Stack>
      <SectionHeading>Size Medium</SectionHeading>
      <Select
        id="optionSelect-medium"
        name="optionSelect-medium"
        defaultValue="optionTwo"
      >
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Option 2</Select.Option>
        <Select.Option value="optionThree" isDisabled>
          Disabled option
        </Select.Option>
      </Select>
      <SectionHeading>Size Small</SectionHeading>
      <Select
        id="optionSelect-small"
        name="optionSelect-small"
        size="small"
        defaultValue="optionTwo"
      >
        <Select.Option value="optionOne">Option 1</Select.Option>
        <Select.Option value="optionTwo">Option 2</Select.Option>
        <Select.Option value="optionThree" isDisabled>
          Disabled option
        </Select.Option>
      </Select>
    </Stack>
  );
}
Open in Playground

Select disabled state


function SelectDisabledExample() {
  return (
    <Select id="optionSelect" name="optionSelect" isDisabled>
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}function SelectDisabledExample() {
  return (
    <Select id="optionSelect" name="optionSelect" isDisabled>
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}
Open in Playground

Select with placeholder


function SelectPlaceholderExample() {
  return (
    <Select name="optionSelect" id="optionSelect" defaultValue="">
      <Select.Option value="" isDisabled>
        Please select an option...
      </Select.Option>
      <Select.Option value="optionOne">Option One</Select.Option>
      <Select.Option value="optionTwo">Option Two</Select.Option>
      <Select.Option value="optionThree" isDisabled>
        Option Three
      </Select.Option>
    </Select>
  );
}function SelectPlaceholderExample() {
  return (
    <Select name="optionSelect" id="optionSelect" defaultValue="">
      <Select.Option value="" isDisabled>
        Please select an option...
      </Select.Option>
      <Select.Option value="optionOne">Option One</Select.Option>
      <Select.Option value="optionTwo">Option Two</Select.Option>
      <Select.Option value="optionThree" isDisabled>
        Option Three
      </Select.Option>
    </Select>
  );
}
Open in Playground

Select with error


function SelectWithErrorExample() {
  return (
    <Select id="optionSelect" name="optionSelect" isInvalid>
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}function SelectWithErrorExample() {
  return (
    <Select id="optionSelect" name="optionSelect" isInvalid>
      <Select.Option value="optionOne">Option 1</Select.Option>
      <Select.Option value="optionTwo">Long Option 2</Select.Option>
    </Select>
  );
}
Open in Playground

Content guidelines

Use Select to present many different options in one component
When you have only a few options try to show them all at once, using Radio.
Use Select in Forms
Order the list of options in a logical way, so it make sense for the user
Don't use Select for a very long list of options, instead for those cases use Autocomplete
Options should be written in sentence case (the first word capitalized, the rest lowercase).
Options should be labeled in a clear way, so it's obvious what the option will do

Dropdown menus are typically used for navigation or command menus, where an action is initiated based on the selection.
Select is a type of input, where the user is choosing one option from the list, typically used in Forms.

Accessibility

To ensure Select meets accessibility keyboard standards, set the name and id properties.
The component should be wrapped in a <FormControl> and set a label via <FormControl.Label.
Make use of <FormControl.HelpText> and <FormControl.ValidationMessage> to provide further context
For more information about validation and controlling form fields, please refer to FormControl.

Keyboard Usage

Use the “arrow keys (“←”, ”↑”. “→”, and “↓”) + enter” to send the form.
To switch between options with the keyboard, use the “tab + space” and the arrow keys.

Props (API reference)

Open in Storybook

Select

Name	Type	Default
children required	ReactNode
className	string CSS class to be appended to the root element
css	string number false true ComponentSelector Keyframes SerializedStyles ArrayInterpolation<undefined> ObjectInterpolation<undefined> (theme: any) => Interpolation<undefined>
defaultValue	string	undefined
isDisabled	false true
isInvalid	false true
isRequired	false true
onChange	ChangeEventHandler<HTMLSelectElement>
size	"small" "medium"	medium
testId	string A [data-test-id] attribute used for testing purposes	cf-ui-select
value	string	undefined
willBlurOnEsc	false true	true

Select Option

Name	Type	Default
className	string CSS class to be appended to the root element
css	string number false true ComponentSelector Keyframes SerializedStyles ArrayInterpolation<undefined> ObjectInterpolation<undefined> (theme: any) => Interpolation<undefined>
isDisabled	false true
testId	string A [data-test-id] attribute used for testing purposes	cf-ui-select-option

Density support

This component supports multiple densities thanks to the useDensity hook and automatically adjusts its styling for each density (when wrapped with the DensityProvider).

High-density support solely available for the default size (medium).