Thumbprint logo

Dropdown

Dropdown for selecting an item from a larger set

Dropdown with state management

Dropdown is a controlled component. This means that the selected option, if any, must be provided as the value prop. The onChange function updates the value when the user selects a new option.

In this example, notice how value is stored within a React.useState object. The onChange function updates the state when the user selects a new option.

function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-1">Select a state</Label>
            <Dropdown id="example-1" size="large" value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Dropdown sizes
Large
This is the default size for Dropdown.
function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-2">Select a state</Label>
            <Dropdown id="example-2" size="large" value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Small
function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-3">Select a state</Label>
            <Dropdown id="example-3" size="small" value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Widths
By default, the Dropdown component renders as an inline-block element. Its width is determined by the option with the longest text.
The isFullWidth prop can be used to set the width to 100%.
Full width
function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-4">Select a state</Label>
            <Dropdown id="example-4" isFullWidth value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Disabled selects
The isDisabled prop visually and functionally disables the Dropdown.
function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-5">Select a state</Label>
            <Dropdown id="example-5" isDisabled value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Dropdown with an error
The hasError prop can be used to visually represent an error.
This prop only changes the select dropdown’s color. It should be used alongside an error message that helps users advance through the form.
function DropdownExample() {
    const [value, setValue] = React.useState('ca');

    return (
        <div>
            <Label for="example-6">Select a state</Label>
            <Dropdown id="example-6" hasError value={value} onChange={v => setValue(v)}>
                <option value="ny">New York</option>
                <option value="ca">California</option>
                <option value="tn">Tennessee</option>
                <option value="fl">Florida</option>
            </Dropdown>
        </div>
    );
}

Usage with TypeScript
The Dropdown can be passed a TypeScript type for the value prop.
This is useful when you are using Dropdown to select between values of an Enum. This same type will be received by the onChange prop.
enum State {
    CA,
    NY,
    TN,
    FL,
}


function DropdownExample() {
    const [value, setValue] = React.useState<State>(State.CA);


    return (
        <div>
            <Label for="example-7">Select a state</Label>
            <Dropdown<State> id="example-7" hasError value={value} onChange={v => setValue(v)}>
                <option value={State.NY}>New York</option>
                <option value={State.CA}>California</option>
                <option value={State.TN}>Tennessee</option>
                <option value={State.FL}>Florida</option>
            </Dropdown>
        </div>
    );
}
Props
Dropdown
  • value
    required
    The value of the <option> that is selected. See React documentation
on <select> and controlled components
to learn more.
    

    Type
    T
  • onChange
    required
    A function that is fired when the value of the select changes. The
new value is passed to the function.
    

    Type
    (value: T, event: React.ChangeEvent<HTMLSelectElement>) => void
  • children
    A collection of HTML <option> elements.
    

    Type
    React.ReactNode
  • id
    Adds a HTML id attribute to the select. This is used for linking the HTML with a
Label.
    

    Type
    string
  • isDisabled
    Visually and functionally disables the select dropdown.
    

    Type
    boolean
    Default
    false
  • isRequired
    Adds required HTML attribute to element, indicating that an option with a non-empty string
value must be selected.
    

    Type
    boolean
    Default
    false
  • hasError
    Makes the radio and text color red.
    

    Type
    boolean
    Default
    false
  • size
    Changes the select’s font-size, height, and padding.
    

    Type
    'small' | 'large'
    Default
    'large'
  • isFullWidth
    Set the <select>'s width to 100% as opposed to the default behavior
of only taking up the necessary width.
    

    Type
    boolean
    Default
    false
  • onClick
    Function that is fired when the value of the select changes.
    

    Type
    (event: React.MouseEvent<HTMLSelectElement, MouseEvent>) => void
    Default
    (): void => {}
  • onFocus
    Fires when the select receives focus.
    

    Type
    (event: React.FocusEvent<HTMLSelectElement>) => void
  • onBlur
    Fires when the select loses focus.
    

    Type
    (event: React.FocusEvent<HTMLSelectElement>) => void
  • dataTestId
    A selector hook into the React component for use in automated testing environments.
    

    Type
    string
  • dataTest
    deprecated
    A selector hook into the React component for use in automated testing environments.
    

    Note: 
    Deprecated in favor of the dataTestId prop
    

    Type
    string
  • name
    Adds name HTML attribute to element, indicating the property name associated with the
selected value.
    

    Type
    string
  • accessibilityLabel
    This adds an aria-label to the element. It should only be used in cases where the
<Dropdown> doesn't have or can't be associated with a related <label>. Learn more about
the importance of using labels.
    

    Type
    string