dcc.RadioItems

dcc.RadioItems is a component for rendering a set of radio (or option) buttons. Users can select one option from the set.
See Checklist
for selecting multiple options at a time, and
Dropdown for
a more compact view.

Examples

Find a few usage examples below.

For more examples of minimal Dash apps that use dcc.RadioItems, go to the community-driven Example Index.

Basic RadioItems

To create a basic radioitems, provide options and a value to the dcc.RadioItems component in that order.

from dash import Dash, dcc

app = Dash(__name__)

app.layout = dcc.RadioItems(['New York City', 'Montreal','San Francisco'], 'Montreal')

if __name__ == "__main__":
    app.run(debug=True)

Horizontal Options

The above example’s labels on the RadioItems are displayed vertically. Setinline=True for labels for them to be displayed horizontally:

from dash import Dash, dcc

app = Dash(__name__)

app.layout = dcc.RadioItems(['New York City', 'Montreal','San Francisco'], 'Montreal', inline=True)

if __name__ == "__main__":
    app.run(debug=True)

In the example above, by setting inline=True, we configured the RadioItems to be displayed horizontally.

This property is a shorthand for setting it on the labelStyle property and is available from Dash 2.1.
The same can be done with labelStyle={'display': 'inline-block'} in earlier versions of Dash.

Options and Value

The options and value properties are the first two arguments of dcc.RadioItems. There are multiple ways to set options. The following examples define the same RadioItems component:

dcc.RadioItems(['New York City', 'Montreal', 'San Francisco'], 'Montreal')
dcc.RadioItems(
   options=['New York City', 'Montreal', 'San Francisco'],
   value='Montreal'
)
dcc.RadioItems(
   options=[
       {'label': 'New York City', 'value': 'New York City'},
       {'label': 'Montreal', 'value': 'Montreal'},
       {'label': 'San Francisco', 'value': 'San Francisco'},
   ],
   value='Montreal'
)
dcc.RadioItems(
   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.RadioItems(
   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.RadioItems(
   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 and value, and also options must be provided as a list of dictionaries.

Disable Options

from dash import Dash, dcc

app = Dash(__name__)

app.layout = dcc.RadioItems([
        {'label': 'New York City', 'value': 'NYC'},
        {'label': 'Montréal', 'value': 'MTL'},
        {'label': 'San Francisco', 'value': 'SF', 'disabled': True}
    ],
    'MTL'
)

if __name__ == "__main__":
    app.run(debug=True)

Flexible Data Types

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 options.

from dash import Dash, dcc
from plotly.express import data
import pandas as pd

df =  data.medals_long()

app = Dash(__name__)

app.layout = dcc.RadioItems(df.columns, df.columns[0])

if __name__ == "__main__":
    app.run(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 RadioItems component displays all unique values in that column.

from dash import Dash, dcc
from plotly.express import data
import pandas as pd

df =  data.medals_long()

app = Dash(__name__)

app.layout = dcc.RadioItems(df.nation.unique(),df.nation.unique()[1])

if __name__ == "__main__":
    app.run(debug=True)

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 a list of components containing an html.Img and text in an html.Span.

from dash import dcc, html

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

Styling Components as Option Labels

This feature is available in Dash 2.5 and later.

You can also style labels by using html.Div components for each label and then setting styles using the style property:

from dash import dcc, html

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

RadioItems Properties

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

help(dash.dcc.RadioItems)
```

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, or inline dictionary of options.

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 (list of or a singular dash component, string or 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; optional):
The currently selected value.

inline (boolean; default False):
Indicates whether the options labels should be displayed inline
(True=horizontal) or in a block (False=vertical).

style (dict; optional):
The style of the container (div).

className (string; optional):
The class of the container (div).

inputStyle (dict; optional):
The style of the <input> radio element.

inputClassName (string; default ''):
The class of the <input> radio element.

labelStyle (dict; optional):
The style of the <label> that wraps the radio input and the option’s
label.

labelClassName (string; default ''):
The class of the <label> that wraps the radio input and the option’s
label.

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.