For production Dash apps, Dash Core Components styling and layout
should be managed with Dash Enterprise Design Kit.
To create a basic dropdown, provide options
and a value
to dcc.Dropdown
in that order.
from dash import Dash, dcc, html, Input, Output
app = Dash(__name__)
app.layout = html.Div([
dcc.Dropdown(['NYC', 'MTL', 'SF'], 'NYC', id='demo-dropdown'),
html.Div(id='dd-output-container')
])
@app.callback(
Output('dd-output-container', 'children'),
Input('demo-dropdown', 'value')
)
def update_output(value):
return f'You have selected {value}'
if __name__ == '__main__':
app.run_server(debug=True)
The options and value properties are the first two arguments of dcc.Dropdown
. There are multiple ways to set options
. The following examples define the same Dropdown:
dcc.Dropdown(['NYC', 'MTL', 'SF'], 'NYC')
dcc.Dropdown(
options=['New York City', 'Montreal', 'San Francisco'],
value='Montreal'
)
dcc.Dropdown(
options=[
{'label': 'New York City', 'value': 'New York City'},
{'label': 'Montreal', 'value': 'Montreal'},
{'label': 'San Francisco', 'value': 'San Francisco'},
],
value='Montreal'
)
dcc.Dropdown(
options={
'New York City': 'New York City',
'Montreal': 'Montreal',
'San Francisco': 'San Francisco'
},
value='Montreal'
)
In these examples, the option’s label (what the user sees) and the value (what’s passed into the callback) are equivalent. Often it is helpful for these to be separate so that you can easily change the label without changing the callback logic that uses the value:
dcc.Dropdown(
options={
'NYC': 'New York City',
'MTL': 'Montreal',
'SF': 'San Francisco'
},
value='MTL'
)
Options provided as a single dictionary render in no particular order in the browser.
Providing a list that contains a dictionary for each option ensures the options render in the order provided.
dcc.Dropdown(
options=[
{'label': 'New York City', 'value': 'NYC'},
{'label': 'Montreal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF'},
],
value='MTL'
)
Note: Versions of Dash before 2.1 only support keyword arguments for
options
andvalue
, and alsooptions
must be provided as a list of dictionaries.
A dropdown component with the multi
property set to True
will allow the user to select more than one value
at a time.
from dash import dcc
dcc.Dropdown(
['New York City', 'Montreal', 'San Francisco'],
['Montreal', 'San Francisco'],
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.
from dash import dcc
dcc.Dropdown(
['New York City', 'Montreal', 'San Francisco'],
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
from dash import dcc
dcc.Dropdown(
['New York City', 'Montreal', 'San Francisco'],
'Montreal',
clearable=False
)
The placeholder
property allows you to define
default text shown when no value is selected.
from dash import dcc
dcc.Dropdown(
['New York City', 'Montreal', 'San Francisco'],
placeholder="Select a city",
)
To disable the dropdown just set disabled
to True
.
from dash import dcc
dcc.Dropdown(
['New York City', 'Montreal', 'San Francisco'],
disabled=True
)
To disable a particular option inside the dropdown
menu, set the disabled
property in the options.
from dash import dcc
dcc.Dropdown([
{'label': 'New York City', 'value': 'NYC', 'disabled': True},
{'label': 'Montreal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF', 'disabled': True}])
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.
from dash import Dash, dcc, html, dcc, Input, Output, State
from dash.exceptions import PreventUpdate
options = [
{"label": "New York City", "value": "NYC"},
{"label": "Montreal", "value": "MTL"},
{"label": "San Francisco", "value": "SF"},
]
app = 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)
We’ve seen how options
can be set using a list, a dictionary, or a list of dictionaries. options
also accepts Pandas and NumPy data structures.
In this example, we use the DataFrame’s columns (df.columns
) as the dropdown options
.
from dash import Dash, dcc, html, Input, Output
from plotly.express import data
import pandas as pd
df = data.medals_long()
app = Dash(__name__)
app.layout = html.Div([
dcc.Dropdown(df.columns, id='pandas-dropdown-1'),
html.Div(id='pandas-output-container-1')
])
@app.callback(
Output('pandas-output-container-1', 'children'),
Input('pandas-dropdown-1', 'value')
)
def update_output(value):
return f'You have selected {value}'
if __name__ == '__main__':
app.run_server(debug=True)
Here, we set options
with df.nation.unique()
. This Pandas method returns unique values in the ‘nation’ column. By passing it to options
, our dropdown displays all unique values in that column.
from dash import Dash, dcc, html, Input, Output
from plotly.express import data
import pandas as pd
df = data.medals_long()
app = Dash(__name__)
app.layout = html.Div([
dcc.Dropdown(df.nation.unique(), id='pandas-dropdown-2'),
html.Div(id='pandas-output-container-2')
])
@app.callback(
Output('pandas-output-container-2', 'children'),
Input('pandas-dropdown-2', 'value')
)
def update_output(value):
return f'You have selected {value}'
if __name__ == '__main__':
app.run_server(debug=True)
Access this documentation in your Python terminal with:
```pythonhelp(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.
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 strings | numbers | booleans | dict | list of
dicts with keys:
disabled
(boolean; optional):
If True, this option is disabled and cannot be selected.
label
(string | number; required):
The option’s label.
title
(string; optional):
The HTML ‘title’ attribute for the option. Allows for information
on hover. For more information on this attribute, see
https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title.
value
(string | number | boolean; required):
The value of the option. This value corresponds to the items
specified in the value
property.
value
(string | number | boolean | list of strings | numbers | booleans; 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.
multi
(boolean; default False
):
If True, the user can select multiple values.
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.
searchable
(boolean; default True
):
Whether to enable the searching feature or not.
search_value
(string; optional):
The value typed in the DropDown for searching.
placeholder
(string; optional):
The grey, default text shown when no option is selected.
disabled
(boolean; default False
):
If True, this dropdown is disabled and the selection cannot be changed.
optionHeight
(number; default 35
):
height of each option. Can be increased when label lengths would wrap
around.
style
(dict; optional):
Defines CSS styles which will override styles previously set.
className
(string; optional):
className of the dropdown element.
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.
loading_state
(dict; optional):
Object that holds the loading state object coming from dash-renderer.
loading_state
is a dict with keys:
component_name
(string; optional):
Holds the name of the component that is loading.
is_loading
(boolean; optional):
Determines if the component is loading or not.
prop_name
(string; optional):
Holds which property is loading.
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
.
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_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.