For production Dash apps, Dash Core Components styling and layout
should be managed with Dash Enterprise Design Kit.
An example of a default dropdown without any extra properties.
import dash
import dash_html_components as html
import dash_core_components as dcc
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
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(
dash.dependencies.Output('dd-output-container', 'children'),
[dash.dependencies.Input('demo-dropdown', 'value')])
def update_output(value):
return 'You have selected "{}"'.format(value)
if __name__ == '__main__':
app.run_server(debug=True)
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 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 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
)
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",
)
To disable the dropdown just set disabled=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
)
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}
],
)
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
external_stylesheets = ["https://codepen.io/chriddyp/pen/bWLwgP.css"]
options = [
{"label": "New York City", "value": "NYC"},
{"label": "Montreal", "value": "MTL"},
{"label": "San Francisco", "value": "SF"},
]
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
app.layout = html.Div(
[
html.Label(["Single dynamic Dropdown", dcc.Dropdown(id="my-dynamic-dropdown")]),
html.Label(
[
"Multi dynamic Dropdown",
dcc.Dropdown(id="my-multi-dynamic-dropdown", multi=True),
]
),
]
)
@app.callback(
dash.dependencies.Output("my-dynamic-dropdown", "options"),
[dash.dependencies.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(
dash.dependencies.Output("my-multi-dynamic-dropdown", "options"),
[dash.dependencies.Input("my-multi-dynamic-dropdown", "search_value")],
[dash.dependencies.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)
Access this documentation in your Python terminal with:
```pythonhelp(dash_core_components.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 has the following type: dict containing keys ‘is_loading’, ‘prop_name’, ‘component_name’. Those keys have the following types:
is_loading
(boolean; optional): Determines if the component is loading or not prop_name
(string; optional): Holds which property is loading component_name
(string; optional): Holds the name of the component that is loadingmulti
(boolean; default False
): If true, the user can select multiple values
options
(dict; optional): An array of options {label: [string|number], value: [string|number]}, an optional disabled field can be used for each option. options has the following type: list of dicts containing keys ‘label’, ‘value’, ‘disabled’, ‘title’. Those keys have the following types:
label
(string | number; required): The dropdown’s label value
(string | number; required): The value of the dropdown. This value corresponds to the items specified in the value
property. disabled
(boolean; optional): If true, this option is disabled and cannot be selected. 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/titleoptionHeight
(number; default 35
): height of each option. Can be increased when label lengths would wrap around
placeholder
(string; optional): The grey, default text shown when no option is selected
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 a value equal to: ‘value’s; 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’, ‘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.
searchable
(boolean; default True
): Whether to enable the searching feature or not
search_value
(string; optional): The value typed in the DropDown for searching.
style
(dict; optional): Defines CSS styles which will override styles previously set.
value
(string | number | list of string | 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.