dcc.Dropdown

For production Dash apps, Dash Core Components styling and layout
should be managed with Dash Enterprise Design Kit.

Default Dropdown

An example of a default dropdown without
any extra properties.

import dash
import dash_html_components as html
import dash_core_components as dcc
from dash.dependencies import Input, Output

app = dash.Dash(__name__)
app.layout = html.Div([
    dcc.Dropdown(
        id='demo-dropdown',
        options=[
            {'label': 'New York City', 'value': 'NYC'},
            {'label': 'Montreal', 'value': 'MTL'},
            {'label': 'San Francisco', 'value': 'SF'}
        ],
        value='NYC'
    ),
    html.Div(id='dd-output-container')
])


@app.callback(
    Output('dd-output-container', 'children'),
    Input('demo-dropdown', 'value')
)
def update_output(value):
    return 'You have selected "{}"'.format(value)


if __name__ == '__main__':
    app.run_server(debug=True)

Multi-Value Dropdown

A dropdown component with the multi property set to True
will allow the user to select more than one value
at a time.

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF'}
    ],
    value=['MTL', 'NYC'],
    multi=True
)

The searchable property is set to True by default on all
dcc.Dropdown components. To prevent searching the dropdown
value, just set the searchable property to False.
Try searching for ‘New York’ on this dropdown below and compare
it to the other dropdowns on the page to see the difference.

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF'}
    ],
    searchable=False
)

The clearable property is set to True by default on all
dcc.Dropdown components. To prevent the clearing of the selected dropdown
value, just set the clearable property to False

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF'}
    ],
    value='MTL',
    clearable=False
)

Placeholder Text

The placeholder property allows you to define
default text shown when no value is selected.

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF'}
    ],
    placeholder="Select a city",
)

Disable Dropdown

To disable the dropdown just set disabled to True.

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF'}
    ],
    disabled=True
)

Disable Options

To disable a particular option inside the dropdown
menu, set the disabled property in the options.

import dash_core_components as dcc

dcc.Dropdown(
    options=[
        {'label': 'New York City', 'value': 'NYC', 'disabled': True},
        {'label': 'Montreal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF', 'disabled': True}
    ]
)

Dynamic Options

This is an example on how to update the options on the server
depending on the search terms the user types. For example purpose
the options are empty on first load, as soon as you start typing
they will be loaded with the corresponding values.

import dash
from dash.exceptions import PreventUpdate
import dash_html_components as html
import dash_core_components as dcc
from dash.dependencies import Input, Output, State

options = [
    {"label": "New York City", "value": "NYC"},
    {"label": "Montreal", "value": "MTL"},
    {"label": "San Francisco", "value": "SF"},
]

app = dash.Dash(__name__)
app.layout = html.Div([
    html.Div([
        "Single dynamic Dropdown",
        dcc.Dropdown(id="my-dynamic-dropdown")
    ]),
    html.Div([
        "Multi dynamic Dropdown",
        dcc.Dropdown(id="my-multi-dynamic-dropdown", multi=True),
    ]),
])


@app.callback(
    Output("my-dynamic-dropdown", "options"),
    Input("my-dynamic-dropdown", "search_value")
)
def update_options(search_value):
    if not search_value:
        raise PreventUpdate
    return [o for o in options if search_value in o["label"]]


@app.callback(
    Output("my-multi-dynamic-dropdown", "options"),
    Input("my-multi-dynamic-dropdown", "search_value"),
    State("my-multi-dynamic-dropdown", "value")
)
def update_multi_options(search_value, value):
    if not search_value:
        raise PreventUpdate
    # Make sure that the set values are in the option list, else they will disappear
    # from the shown select list, but still part of the `value`.
    return [
        o for o in options if search_value in o["label"] or o["value"] in (value or [])
    ]


if __name__ == "__main__":
    app.run_server(debug=True)
Single dynamic Dropdown
Multi dynamic Dropdown

Access this documentation in your Python terminal with:
```python

help(dash.dcc.Dropdown)
```

Our recommended IDE for writing Dash apps is Dash Enterprise’s
Data Science Workspaces,
which has typeahead support for Dash Component Properties.
Find out if your company is using
Dash Enterprise.

id (string; optional):
The ID of this component, used to identify dash components in
callbacks. The ID needs to be unique across all of the components in
an app.

className (string; optional):
className of the dropdown element.

clearable (boolean; default True):
Whether or not the dropdown is “clearable”, that is, whether or not a
small “x” appears on the right of the dropdown that removes the
selected value.

disabled (boolean; default False):
If True, this dropdown is disabled and the selection cannot be changed.

loading_state (dict; optional):
Object that holds the loading state object coming from dash-renderer.

loading_state is a dict with keys:

multi (boolean; default False):
If True, the user can select multiple values.

optionHeight (number; default 35):
height of each option. Can be increased when label lengths would wrap
around.

options (list of dicts; optional):
An array of options {label: [string|number], value: [string|number]},
an optional disabled field can be used for each option.

options is a list of dicts with keys:

persisted_props (list of values equal to: ‘value’; default ['value']):
Properties whose user interactions will persist after refreshing the
component or the page. Since only value is allowed this prop can
normally be ignored.

persistence (boolean | string | number; optional):
Used to allow user interactions in this component to be persisted when
the component - or the page - is refreshed. If persisted is truthy
and hasn’t changed from its previous value, a value that the user
has changed while using the app will keep that change, as long as the
new value also matches what was given originally. Used in
conjunction with persistence_type.

persistence_type (a value equal to: ‘local’, ‘session’ or ‘memory’; default 'local'):
Where persisted user changes will be stored: memory: only kept in
memory, reset on page refresh. local: window.localStorage, data is
kept after the browser quit. session: window.sessionStorage, data is
cleared once the browser quit.

placeholder (string; optional):
The grey, default text shown when no option is selected.

search_value (string; optional):
The value typed in the DropDown for searching.

searchable (boolean; default True):
Whether to enable the searching feature or not.

style (dict; optional):
Defines CSS styles which will override styles previously set.

value (string | number | list of strings | numbers; optional):
The value of the input. If multi is False (the default) then value
is just a string that corresponds to the values provided in the
options property. If multi is True, then multiple values can be
selected at once, and value is an array of items with values
corresponding to those in the options prop.