DCC.Dropdown.dropdown

DCC.Dropdown.dropdown is a component that creates a customizable dropdown menu for selecting one or multiple items from a list of options.

Examples

Find a few usage examples below.

Basic Dropdown

An example of a basic dropdown without any extra properties.

open Dash.NET

let dslLayout = 
    Html.div [
        Attr.children [
            Dropdown.dropdown "demo-dropdown" [
                Dropdown.Attr.options [
                    { Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City" }
                    { Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal" }
                    { Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco" }
                ]
                Dropdown.Attr.value "NYC"
            ]
            Html.div [ Attr.id "dd-output-container" ]
        ]
    ]

let changeTextCallback =
    Callback.singleOut (
        "demo-dropdown" @. Value,
        "dd-output-container" @. Children,
        (fun (dval: string) -> "dd-output-container" @. Children => sprintf "You have selected %s" dval)
        , PreventInitialCall = false
    )

[<EntryPoint>]
let main args =
    DashApp.initDefault()
    |> DashApp.withLayout dslLayout
    |> DashApp.addCallback changeTextCallback
    |> DashApp.run args

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.

open Dash.NET

Dropdown.dropdown "demo-dropdown" [
    Dropdown.Attr.options [
        { Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City" }
        { Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal" }
        { Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco" }
    ]
    Dropdown.Attr.value ["MTL" :> IConvertible ; "NYC" :> IConvertible]
    Dropdown.Attr.multi true
]

The searchable property is set to True by default on all
DCC.Dropdown.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.

open Dash.NET

Dropdown.dropdown "dropdown" [
    Dropdown.Attr.options [
        {Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City"}
        {Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal"}
        {Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco"}
    ]
    Dropdown.Attr.searchable false
]

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

open Dash.NET

Dropdown.dropdown "dropdown" [
    Dropdown.Attr.options [
        {Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City"}
        {Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal"}
        {Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco"}
    ]
    Dropdown.Attr.value "MTL"
    Dropdown.Attr.clearable false
]

Placeholder Text

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

open Dash.NET

Dropdown.dropdown "demo-dropdown" [
    Dropdown.Attr.options [
        { Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City" }
        { Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal" }
        { Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco" }
    ]
    Dropdown.Attr.placeholder "Select a city"
]

Disable Dropdown

To disable the dropdown just set disabled to true.

open Dash.NET

Dropdown.dropdown "dropdown" [
    Dropdown.Attr.options [
        {Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City"}
        {Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal"}
        {Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco"}
    ]
    Dropdown.Attr.disabled true
]

Disable Options

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

open Dash.NET

Dropdown.dropdown "dropdown" [
    Dropdown.Attr.options [
        {Label = "New York City"; Value = "NYC"; Disabled = true; Title = "New York City"}
        {Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal"}
        {Label = "San Francisco"; Value = "SF"; Disabled = true; Title = "San Francisco"}
    ]
]

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.

open Dash.NET

let options: DropdownOption list = [
    {Label = "New York City"; Value = "NYC"; Disabled = false; Title = "New York City"}
    {Label = "Montreal"; Value = "MTL"; Disabled = false; Title = "Montreal"}
    {Label = "San Francisco"; Value = "SF"; Disabled = false; Title = "San Francisco"}
]

let dslLayout = 
    Html.div [
        Attr.children [
            Html.div [
                Attr.children [
                    Html.text "Single dynamic Dropdown"
                    Dropdown.dropdown "my-dynamic-dropdown" [
                        Dropdown.Attr.searchable true
                        Dropdown.Attr.searchValue ""
                        Dropdown.Attr.options []
                    ]
                ]
            ]
            Html.div [
                Attr.children [
                    Html.text "Multi dynamic Dropdown"
                    Dropdown.dropdown "my-multi-dynamic-dropdown" [
                        Dropdown.Attr.searchable true
                        Dropdown.Attr.searchValue ""
                        Dropdown.Attr.options []
                        Dropdown.Attr.value ""
                        Dropdown.Attr.multi true
                    ]
                ]
            ]
        ]
    ]

let updateOptionsCallback =
    Callback.singleOut (
        "my-dynamic-dropdown" @. (CustomProperty "search_value"),
        "my-dynamic-dropdown" @. (CustomProperty "options"),
        fun (sval: string) -> 
            "my-dynamic-dropdown" @. (CustomProperty "options") => (
                options 
                |> List.filter (fun o -> (string o.Label).Contains sval)
            )
        , PreventInitialCall = false
    )

let updateMultiOptionsCallback =
    Callback.singleOut (
        "my-multi-dynamic-dropdown" @. (CustomProperty "search_value"),
        "my-multi-dynamic-dropdown" @. (CustomProperty "options"),
        fun (sval: string) (dval: string) -> 
            "my-multi-dynamic-dropdown" @. (CustomProperty "options") => (
                options 
                |> List.filter (fun o -> 
                    (string o.Label).Contains sval || dval.Contains (string o.Value)
                )
            )
        , State = ["my-multi-dynamic-dropdown" @. (CustomProperty "value")]
        , PreventInitialCall = false
    )

[<EntryPoint>]
let main args =
    DashApp.initDefault()
    |> DashApp.withLayout dslLayout
    |> DashApp.addCallback updateOptionsCallback
    |> DashApp.addCallback updateMultiOptionsCallback
    |> DashApp.run args
Single dynamic Dropdown
Multi dynamic Dropdown

Components as Option Labels

This feature is available in Dash 2.5 and later.

In previous examples, we’ve set option labels as strings. You can also use Dash components as option labels.
In this example, each label is an html.Span component with an html.Img component and some text inside.

This example has not been ported to F# yet - showing the Python version instead.

Visit the old docs site for F# at: https://community.plotly.com/c/dash/net/26

from dash import dcc, html

dcc.Dropdown(
    [
        {
            "label": html.Span(
                [
                    html.Img(src="/assets/images/language_icons/python_50px.svg", height=20),
                    html.Span("Python", style={'font-size': 15, 'padding-left': 10}),
                ], style={'align-items': 'center', 'justify-content': 'center'}
            ),
            "value": "Python",
        },
        {
            "label": html.Span(
                [
                    html.Img(src="/assets/images/language_icons/julia_50px.svg", height=20),
                    html.Span("Julia", style={'font-size': 15, 'padding-left': 10}),
                ], style={'align-items': 'center', 'justify-content': 'center'}
            ),
            "value": "Julia",
        },
        {
            "label": html.Span(
                [
                    html.Img(src="/assets/images/language_icons/r-lang_50px.svg", height=20),
                    html.Span("R", style={'font-size': 15, 'padding-left': 10}),
                ], style={'align-items': 'center', 'justify-content': 'center'}
            ),
            "value": "R",
        },
    ],
    value="Python"
)

Styling Components as Option Labels

This feature is available in Dash 2.5 and later.

You can also style labels by using an html.Span component for each label and then setting styles using the style property:

This example has not been ported to F# yet - showing the Python version instead.

Visit the old docs site for F# at: https://community.plotly.com/c/dash/net/26

from dash import dcc, html

dcc.Dropdown(
    [
        {
            "label": html.Span(['Montreal'], style={'color': 'Gold', 'font-size': 20}),
            "value": "Montreal",
        },
        {
            "label": html.Span(['NYC'], style={'color': 'MediumTurqoise', 'font-size': 20}),
            "value": "NYC",
        },
        {
            "label": html.Span(['London'], style={'color': 'LightGreen', 'font-size': 20}),
            "value": "London",
        },
    ], value='Montreal'
)

Custom Search Values

When you use components as option labels, the dropdown’s search uses the option values by default.
You can add an extra string for the search by setting an option’s search property.
Here we set a search value for each option to match that option’s label text.

The value provided to search is in addition to option value. For example, option 2 is displayed when a user searches
for either ‘NYC’ or ‘New York City’.

This example has not been ported to F# yet - showing the Python version instead.

Visit the old docs site for F# at: https://community.plotly.com/c/dash/net/26

from dash import dcc, html

dcc.Dropdown(
    [
        {
            "label": html.Span(['Montreal'], style={'color': 'Gold', 'font-size': 20}),
            "value": "MTL",
            "search": "Montreal"
        },
        {
            "label": html.Span(['New York City'], style={'color': 'MediumTurqoise', 'font-size': 20}),
            "value": "NYC",
            "search": "New York City"
        },
        {
            "label": html.Span(['London'], style={'color': 'LightGreen', 'font-size': 20}),
            "value": "LON",
            "search": "London"
        },
    ], value='Montreal',
)

The height of an expanded dropdown is 200px by default. Options that fit within this height are visible on screen,
while the remaining options can be accessed using the dropdown’s vertical scrollbar.
You can change the height with maxHeight if you want more or fewer options to be visible when the dropdown is expanded.
In this example, we set it to 300px.

This example has not been ported to F# yet - showing the Python version instead.

Visit the old docs site for F# at: https://community.plotly.com/c/dash/net/26

from dash import dcc

dcc.Dropdown(
    ['New York City', 'Montreal', 'Paris', 'London', 'Amsterdam', 'Berlin', 'Rome'],
    'Paris', id='height-example-dropdown', maxHeight=300
)

Option Height

You can change the height of options in the dropdown by setting optionHeight. In this example, we set it to 50px.
The default is 35px.

This example has not been ported to F# yet - showing the Python version instead.

Visit the old docs site for F# at: https://community.plotly.com/c/dash/net/26

from dash import dcc

dcc.Dropdown(
    ['New York City', 'Montreal', 'Paris', 'London', 'Amsterdam', 'Berlin', 'Rome'],
    'Paris', id='option-height-example-dropdown', optionHeight=50
)

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 records; 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 | bools | record | list of
records with keys:

  • disabled (bool; optional):
    If true, this option is disabled and cannot be selected.

  • label (list of or a singular dash component, string or number; required):
    The option’s label.

  • search (string; optional):
    Optional search value for the option, to use if the label is a
    component or provide a custom search value different from the
    label. If no search value and the label is a component, the
    value will be used for search.

  • 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 | bool; required):
    The value of the option. This value corresponds to the items
    specified in the value property.

value (string | number | bool | list of strings | numbers | bools; 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 (bool; default false):
If true, the user can select multiple values.

clearable (bool; 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 (bool; 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 (bool; 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.

maxHeight (number; default 200):
height of the options dropdown.

style (record; 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 (record; optional):
Object that holds the loading state object coming from dash-renderer.

loading_state is a record with keys:

  • component_name (string; optional):
    Holds the name of the component that is loading.

  • is_loading (bool; optional):
    Determines if the component is loading or not.

  • prop_name (string; optional):
    Holds which property is loading.

persistence (bool | 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.