SelectField

SelectField allows users to select from a menu of options.

Demo

Usage

Import the SelectField primitive, and provide a label for accessibility. The <option> tags nested inside the component define the available options in the drop-down list.

Fruit

import { SelectField } from '@aws-amplify/ui-react';

export const DefaultSelectFieldExample = () => (
  <SelectField label="Fruit">
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
    <option value="zucchini" disabled>
      Zucchini
    </option>
  </SelectField>
);

Accessibility / Label behavior

Controlled component

To manually control the SelectField state, you can use the value and onChange props along with React's useState hook.

import * as React from 'react';
import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldControlledExample = () => {
  const [value, setValue] = React.useState('');

  return (
    <SelectField
      label="Fruit"
      labelHidden
      placeholder="This SelectField is manually controlled"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    >
      <option value="x">X</option>
      <option value="y">Y</option>
      <option value="z">Z</option>
    </SelectField>
  );
};

Options

Create a simple SelectField by passing a list to the options prop.

Animals

This is the same as the example above

import { SelectField, Flex } from '@aws-amplify/ui-react';

export const SelectFieldOptionsExample = () => (
  <Flex direction="column">
    <SelectField
      label="Animals"
      options={['lions', 'tigers', 'bears']}
    ></SelectField>

    <SelectField label="This is the same as the example above">
      <option value="lions" label="lions">
        lions
      </option>
      <option value="tigers" label="tigers">
        tigers
      </option>
      <option value="bears" label="bears">
        bears
      </option>
    </SelectField>
  </Flex>
);

Sizes

Use the size prop to change the SelectField size. Available options are small, large, and none (default).

import { SelectField, Flex } from '@aws-amplify/ui-react';

export const SelectFieldSizeExample = () => (
  <Flex direction="column">
    <SelectField size="small" label="small" labelHidden>
      <option>small</option>
    </SelectField>
    <SelectField label="default" labelHidden>
      <option>default</option>
    </SelectField>
    <SelectField size="large" label="large" labelHidden>
      <option>large</option>
    </SelectField>
  </Flex>
);

Variations

There are two variation styles available: default and quiet.

import { SelectField, Flex } from '@aws-amplify/ui-react';

export const SelectFieldVariationExample = () => (
  <Flex direction="column">
    <SelectField label="default" labelHidden>
      <option>default</option>
    </SelectField>
    <SelectField variation="quiet" label="quiet" labelHidden>
      <option>quiet</option>
    </SelectField>
  </Flex>
);

Placeholder

Text that appears in the form control when it has no value set.

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldPlaceholderExample = () => (
  <SelectField
    placeholder="This is the placeholder..."
    label="placeholderExample"
    labelHidden
  >
    <option value="option">This is the option</option>
  </SelectField>
);

Descriptive text

The descriptiveText prop will only be visible when label is not hidden (i.e., labelHidden={false}). You can use it to provide some additional description of the field.

SelectField

What do you think of the SelectField?

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldDescriptiveTextExample = () => (
  <SelectField
    label="SelectField"
    descriptiveText="What do you think of the SelectField?"
  >
    <option value="amazing">It is amazing</option>
    <option value="wow">WOW!</option>
    <option value="incredible">Just incredible</option>
  </SelectField>
);

Icon

You can change the icon used to expand the SelectField by using the icon prop. You can also change the icon's color by passing the iconColor prop.

import { Icon, SelectField } from '@aws-amplify/ui-react';

const IconArrowDropDown = () => {
  return <Icon pathData="M7 10L12 15L17 10H7Z" ariaLabel="Down arrow" />;
};

export const SelectFieldIconExample = () => (
  <SelectField
    label="Icon example"
    labelHidden
    icon={<IconArrowDropDown />}
    iconColor="red"
    placeholder="Check out that Icon! ---> "
  >
    <option value="cool">Pretty cool, right?</option>
  </SelectField>
);

Disabled state

A disabled field will not be focusable or mutable, and it will not be submitted with form data. Use the isDisabled prop to set the state for the SelectField.

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldDisabledStateExample = () => (
  <SelectField isDisabled label="SelectField" labelHidden>
    <option value="option">You cannot view or select this option</option>
  </SelectField>
);

Multiple selections

Use the isMultiple prop to specify that multiple options can be selected at once.

For Mac: Hold down the command button to select multiple options
For Windows: Hold down the control button to select multiple options

Fruit

What's your favorite fruit?

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldMultipleStateExample = () => (
  <SelectField
    label="Fruit"
    descriptiveText="What's your favorite fruit?"
    isMultiple={true}
  >
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
    <option value="pineapple">Pineapple</option>
    <option value="kiwi">Kiwi</option>
    <option value="tangerine">Tangerine</option>
  </SelectField>
);

Select size

Use the selectSize prop to set the number of visible options in a drop-down list. If the value of the selectSize attribute is greater than 1, but lower than the total number of options in the list, the browser will add a scroll bar to indicate that there are more options to view.

Fruit

What's your favorite fruit?

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldSelectSizeExample = () => (
  <SelectField
    label="Fruit"
    descriptiveText="What's your favorite fruit?"
    selectSize={3}
  >
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
    <option value="pineapple">Pineapple</option>
    <option value="kiwi">Kiwi</option>
    <option value="tangerine">Tangerine</option>
  </SelectField>
);

Validation error

Use the hasError and errorMessage props to mark a SelectField as having a validation error.

This is a required field.

import { SelectField } from '@aws-amplify/ui-react';

export const SelectFieldValidationErrorExample = () => (
  <SelectField
    label="Fruit"
    labelHidden
    hasError={true}
    errorMessage="This is a required field."
  >
    <option value="uh oh">Uh oh</option>
  </SelectField>
);

Standard HTML attributes

The SelectField will accept any of the standard HTML attributes that a <select> element accepts. Standard <select> attributes can be found in the MDN Documentation

Fruit

<SelectField label="Fruit" name="fruit">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="orange">Orange</option>
</SelectField>

Styling

Theme

You can customize the appearance of all SelectField components in your application with a Theme.

SelectField Theme Source

Fruit

import { SelectField, ThemeProvider, Theme } from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'selectfield-theme',
  tokens: {
    components: {
      selectfield: {
        color: { value: '{colors.blue.60}' },
        fontSize: { value: '{fontSizes.large}' },
        borderColor: { value: '{colors.red.60}' },
        _focus: {
          borderColor: { value: '{colors.red.80}' },
        },
        label: {
          color: { value: '{colors.blue.60}' },
        },
      },
    },
  },
};

export const SelectFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <SelectField label="Fruit">
      <option value="apple">Apple</option>
      <option value="banana">Banana</option>
      <option value="orange">Orange</option>
    </SelectField>
  </ThemeProvider>
);

Icons

Fruit

import { SelectField, IconsProvider } from '@aws-amplify/ui-react';
import { FiChevronsDown } from 'react-icons/fi';

export const SelectFieldIconProviderExample = () => (
  <IconsProvider
    icons={{
      select: {
        expand: <FiChevronsDown />,
      },
    }}
  >
    <SelectField label="Fruit">
      <option value="apple">Apple</option>
      <option value="banana">Banana</option>
      <option value="orange">Orange</option>
    </SelectField>
  </IconsProvider>
);

Target classes

Class	Description
`amplify-select`	Class applied to the select element
`amplify-selectfield`	Top level element that wraps the SelectField primitive
`amplify-select__wrapper`	Class applied to the select wrapper
`amplify-select__icon`	Class applied to the select icon wrapper

--amplify-components-selectfield-border-color
--amplify-components-selectfield-color
--amplify-components-selectfield-flex-direction
--amplify-components-selectfield-focus-border-color
--amplify-components-selectfield-font-size
--amplify-components-selectfield-label-color

Global styling

To override styling on all SelectFields, you can set the Amplify CSS variables with the built-in .amplify-selectfield class.

Globally styled field

/* styles.css */
.amplify-selectfield {
  --amplify-components-fieldcontrol-border-color: rebeccapurple;
}

Local styling

To override styling on a specific SelectField, you can use a class selector or style props.

Using a class selector:

/* styles.css */
.my-custom-selectfield .amplify-select {
  border-radius: 0;
}

Using style props:

Fruit

import { SelectField, useTheme } from '@aws-amplify/ui-react';

export const SelectFieldStylePropsExample = () => {
  const { tokens } = useTheme();
  return (
    <>
      <SelectField
        label="Fruit"
        padding="xl"
        border={`1px solid ${tokens.colors.primary[60]}`}
      >
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
      </SelectField>
      <SelectField
        label="Fruit"
        inputStyles={{
          backgroundColor: 'primary.10',
          border: `1px solid ${tokens.colors.primary[60]}`,
        }}
      >
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
      </SelectField>
    </>
  );
};