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.
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.
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.
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
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.
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.
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
<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
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
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.
/* 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:
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> </> ); };