Basic Callbacks | Dash for Python Documentation

This is the 3rd chapter of the Dash Tutorial.
The previous chapter covered the Dash app <code>layout<code>
and the next chapter covers interactive graphing.
Just getting started? Make sure to install the necessary dependencies.

In the previous chapter on
app.layout we learned that the app.layout describes what the app
looks like and is a hierarchical tree of components.
The dash_html_components library provides classes for all of the HTML
tags, and the keyword arguments describe the HTML attributes like
style, className, and id. The dash_core_components library
generates higher-level components like controls and graphs.

This chapter describes how to make your
Dash apps interactive.

Let’s get started with a simple example.

Dash App Layout

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

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

app.layout = html.Div([
    dcc.Input(id='my-id', value='initial value', type='text'),
    html.Div(id='my-div')
])


@app.callback(
    Output(component_id='my-div', component_property='children'),
    [Input(component_id='my-id', component_property='value')]
)
def update_output_div(input_value):
    return 'You\'ve entered "{}"'.format(input_value)


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

Try typing in the text box. The children of the output component updates
right away. Let’s break down what’s happening here:

The “inputs” and “outputs” of our application interface are described
declaratively through the app.callback decorator.
In Dash, the inputs and outputs of our application are simply the
properties of a particular component. In this example,
our input is the “value” property of the component that has the ID
“my-id”. Our output is the “children” property of the
component with the ID “my-div”.
Whenever an input property changes, the function that the
callback decorator wraps will get called automatically.
Dash provides the function with the new value of the input property as
an input argument and Dash updates the property of the output component
with whatever was returned by the function.
The component_id and component_property keywords are optional
(there are only two arguments for each of those objects).
I have included them here for clarity but I will omit them from here on
out for brevity and readability.
Don’t confuse the dash.dependencies.Input object and the
dash_core_components.Input object. The former is just used in these
callbacks and the latter is an actual component.
Notice how we don’t set a value for the children property of the
my-div component in the layout. When the Dash app starts, it
automatically calls all of the callbacks with the initial values of the
input components in order to populate the initial state of the output
components. In this example, if you specified something like
html.Div(id='my-div', children='Hello world'), it would get
overwritten when the app starts.

It’s sort of like programming with Microsoft Excel:
whenever an input cell changes, all of the cells that depend on that cell
will get updated automatically. This is called “Reactive Programming”.

Remember how every component was described entirely through its set of
keyword arguments? Those properties are important now.
With Dash interactivity, we can dynamically update any of those properties
through a callback function. Frequently we’ll update the children of a
component to display new text or the figure of a dcc.Graph component
to display new data, but we could also update the style of a component or
even the available options of a dcc.Dropdown component!

Let’s take a look at another example where a dcc.Slider updates a
dcc.Graph.

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

import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminderDataFiveYear.csv')

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

app.layout = html.Div([
    dcc.Graph(id='graph-with-slider'),
    dcc.Slider(
        id='year-slider',
        min=df['year'].min(),
        max=df['year'].max(),
        value=df['year'].min(),
        marks={str(year): str(year) for year in df['year'].unique()},
        step=None
    )
])


@app.callback(
    Output('graph-with-slider', 'figure'),
    [Input('year-slider', 'value')])
def update_figure(selected_year):
    filtered_df = df[df.year == selected_year]
    traces = []
    for i in filtered_df.continent.unique():
        df_by_continent = filtered_df[filtered_df['continent'] == i]
        traces.append(dict(
            x=df_by_continent['gdpPercap'],
            y=df_by_continent['lifeExp'],
            text=df_by_continent['country'],
            mode='markers',
            opacity=0.7,
            marker={
                'size': 15,
                'line': {'width': 0.5, 'color': 'white'}
            },
            name=i
        ))

    return {
        'data': traces,
        'layout': dict(
            xaxis={'type': 'log', 'title': 'GDP Per Capita',
                   'range':[2.3, 4.8]},
            yaxis={'title': 'Life Expectancy', 'range': [20, 90]},
            margin={'l': 40, 'b': 40, 't': 10, 'r': 10},
            legend={'x': 0, 'y': 1},
            hovermode='closest',
            transition = {'duration': 500},
        )
    }


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

In this example, the "value" property of the Slider is the input of the
app and the output of the app is the "figure" property of the Graph.
Whenever the value of the Slider changes, Dash calls the callback
function update_figure with the new value. The function filters the
dataframe with this new value, constructs a figure object,
and returns it to the Dash application.

There are a few nice patterns in this example:

We’re using the Pandas library for
importing and filtering datasets in memory.
We load our dataframe at the start of the app:
df = pd.read_csv('...').
This dataframe df is in the global state of the app and can be
read inside the callback functions.
Loading data into memory can be expensive. By loading querying data at
the start of the app instead of inside the callback functions, we ensure
that this operation is only done when the app server starts. When a user
visits the app or interacts with the app, that data (the df)
is already in memory.
If possible, expensive initialization (like downloading or querying
data) should be done in the global scope of the app instead of within
the callback functions.
The callback does not modify the original data, it just creates copies
of the dataframe by filtering through pandas filters.
This is important: your callbacks should never mutate variables
outside of their scope. If your callbacks modify global state, then one
user’s session might affect the next user’s session and when the app is
deployed on multiple processes or threads, those modifications will not
be shared across sessions.
We are turning on transitions with layout.transition to give an idea
of how the dataset evolves with time: transitions allow the chart to
update from one state to the next smoothly, as if it were animated.

Multiple inputs

In Dash, any “Output” can have multiple “Input” components.
Here’s a simple example that binds five Inputs
(the value property of 2 Dropdown components,
2 RadioItems components, and 1 Slider component)
to 1 Output component (the figure property of the Graph component).
Notice how the app.callback lists all five dash.dependencies.Input
inside a list in the second argument.

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

import pandas as pd

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

df = pd.read_csv('https://plotly.github.io/datasets/country_indicators.csv')

available_indicators = df['Indicator Name'].unique()

app.layout = html.Div([
    html.Div([

        html.Div([
            dcc.Dropdown(
                id='xaxis-column',
                options=[{'label': i, 'value': i} for i in available_indicators],
                value='Fertility rate, total (births per woman)'
            ),
            dcc.RadioItems(
                id='xaxis-type',
                options=[{'label': i, 'value': i} for i in ['Linear', 'Log']],
                value='Linear',
                labelStyle={'display': 'inline-block'}
            )
        ],
        style={'width': '48%', 'display': 'inline-block'}),

        html.Div([
            dcc.Dropdown(
                id='yaxis-column',
                options=[{'label': i, 'value': i} for i in available_indicators],
                value='Life expectancy at birth, total (years)'
            ),
            dcc.RadioItems(
                id='yaxis-type',
                options=[{'label': i, 'value': i} for i in ['Linear', 'Log']],
                value='Linear',
                labelStyle={'display': 'inline-block'}
            )
        ],style={'width': '48%', 'float': 'right', 'display': 'inline-block'})
    ]),

    dcc.Graph(id='indicator-graphic'),

    dcc.Slider(
        id='year--slider',
        min=df['Year'].min(),
        max=df['Year'].max(),
        value=df['Year'].max(),
        marks={str(year): str(year) for year in df['Year'].unique()},
        step=None
    )
])

@app.callback(
    Output('indicator-graphic', 'figure'),
    [Input('xaxis-column', 'value'),
     Input('yaxis-column', 'value'),
     Input('xaxis-type', 'value'),
     Input('yaxis-type', 'value'),
     Input('year--slider', 'value')])
def update_graph(xaxis_column_name, yaxis_column_name,
                 xaxis_type, yaxis_type,
                 year_value):
    dff = df[df['Year'] == year_value]

    return {
        'data': [dict(
            x=dff[dff['Indicator Name'] == xaxis_column_name]['Value'],
            y=dff[dff['Indicator Name'] == yaxis_column_name]['Value'],
            text=dff[dff['Indicator Name'] == yaxis_column_name]['Country Name'],
            mode='markers',
            marker={
                'size': 15,
                'opacity': 0.5,
                'line': {'width': 0.5, 'color': 'white'}
            }
        )],
        'layout': dict(
            xaxis={
                'title': xaxis_column_name,
                'type': 'linear' if xaxis_type == 'Linear' else 'log'
            },
            yaxis={
                'title': yaxis_column_name,
                'type': 'linear' if yaxis_type == 'Linear' else 'log'
            },
            margin={'l': 40, 'b': 40, 't': 10, 'r': 0},
            hovermode='closest'
        )
    }


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

In this example, the update_graph function gets called whenever the
value property of the Dropdown, Slider, or RadioItems components
change.

The input arguments of the update_graph function are the new or current
value of each of the Input properties, in the order that they were
specified.

Even though only a single Input changes at a time (a user can only change
the value of a single Dropdown in a given moment), Dash collects the
current state of all of the specified Input properties and passes them
into your function for you. Your callback functions are always guaranteed
to be passed the representative state of the app.

Let’s extend our example to include multiple outputs.

Multiple Outputs

New in dash 0.39.0

So far all the callbacks we’ve written only update a
single Output property. We can also update several at once: put all the
properties you want to update as a list in the decorator, and return that
many items from the callback. This is particularly nice if two outputs
depend on the same computationally intense intermediate result, such as a
slow database query.

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

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

app.layout = html.Div([
    dcc.Input(
        id='num-multi',
        type='number',
        value=5
    ),
    html.Table([
        html.Tr([html.Td(['x', html.Sup(2)]), html.Td(id='square')]),
        html.Tr([html.Td(['x', html.Sup(3)]), html.Td(id='cube')]),
        html.Tr([html.Td([2, html.Sup('x')]), html.Td(id='twos')]),
        html.Tr([html.Td([3, html.Sup('x')]), html.Td(id='threes')]),
        html.Tr([html.Td(['x', html.Sup('x')]), html.Td(id='x^x')]),
    ]),
])


@app.callback(
    [Output('square', 'children'),
     Output('cube', 'children'),
     Output('twos', 'children'),
     Output('threes', 'children'),
     Output('x^x', 'children')],
    [Input('num-multi', 'value')])
def callback_a(x):
    return x**2, x**3, 2**x, 3**x, x**x


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

x ²
x ³
2 ^x
3 ^x
x ^x

A word of caution: it’s not always a good idea to combine Outputs, even if
you can:

If the Outputs depend on some but not all of the same Inputs, keeping
them separate can avoid unnecessary updates.
If they have the same Inputs but do independent computations with these
inputs, keeping the callbacks separate can allow them to run in parallel.

Chained Callbacks

You can also chain outputs and inputs together: the output of one callback
function could be the input of another callback function.

This pattern can be used to create dynamic UIs where one input component
updates the available options of the next input component.
Here’s a simple example.

# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

all_options = {
    'America': ['New York City', 'San Francisco', 'Cincinnati'],
    'Canada': [u'Montréal', 'Toronto', 'Ottawa']
}
app.layout = html.Div([
    dcc.RadioItems(
        id='countries-radio',
        options=[{'label': k, 'value': k} for k in all_options.keys()],
        value='America'
    ),

    html.Hr(),

    dcc.RadioItems(id='cities-radio'),

    html.Hr(),

    html.Div(id='display-selected-values')
])


@app.callback(
    Output('cities-radio', 'options'),
    [Input('countries-radio', 'value')])
def set_cities_options(selected_country):
    return [{'label': i, 'value': i} for i in all_options[selected_country]]


@app.callback(
    Output('cities-radio', 'value'),
    [Input('cities-radio', 'options')])
def set_cities_value(available_options):
    return available_options[0]['value']


@app.callback(
    Output('display-selected-values', 'children'),
    [Input('countries-radio', 'value'),
     Input('cities-radio', 'value')])
def set_display_children(selected_country, selected_city):
    return u'{} is a city in {}'.format(
        selected_city, selected_country,
    )


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

The first callback updates the available options in the second RadioItems
component based off of the selected value in the first RadioItems
component.

The second callback sets an initial value when the options property
changes: it sets it to the first value in that options array.

The final callback displays the selected value of each component.
If you change the value of the countries RadioItems component, Dash
will wait until the value of the cities component is updated
before calling the final callback. This prevents your callbacks from being
called with inconsistent state like with "America" and "Montréal".

State

In some cases, you might have a “form”-type pattern in your
application. In such a situation, you might want to read the value
of the input component, but only when the user is finished
entering all of his or her information in the form.

Attaching a callback to the input values directly can look like
this:

# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output

external_stylesheets = ["https://codepen.io/chriddyp/pen/bWLwgP.css"]

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

app.layout = html.Div(
    [
        dcc.Input(id="input-1", type="text", value="Montréal"),
        dcc.Input(id="input-2", type="text", value="Canada"),
        html.Div(id="number-output"),
    ]
)


@app.callback(
    Output("number-output", "children"),
    [Input("input-1", "value"), Input("input-2", "value")],
)
def update_output(input1, input2):
    return u'Input 1 is "{}" and Input 2 is "{}"'.format(input1, input2)


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

In this example, the callback function is fired whenever any of the
attributes described by the dash.dependencies.Input change.
Try it for yourself by entering data in the inputs above.

dash.dependencies.State allows you to pass along extra values without
firing the callbacks. Here’s the same example as above but with the
dcc.Input as dash.dependencies.State and a button as
dash.dependencies.Input.

# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output, State

external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']

app = dash.Dash(__name__, external_stylesheets=external_stylesheets)

app.layout = html.Div([
    dcc.Input(id='input-1-state', type='text', value='Montréal'),
    dcc.Input(id='input-2-state', type='text', value='Canada'),
    html.Button(id='submit-button-state', n_clicks=0, children='Submit'),
    html.Div(id='output-state')
])


@app.callback(Output('output-state', 'children'),
              [Input('submit-button-state', 'n_clicks')],
              [State('input-1-state', 'value'),
               State('input-2-state', 'value')])
def update_output(n_clicks, input1, input2):
    return u'''
        The Button has been pressed {} times,
        Input 1 is "{}",
        and Input 2 is "{}"
    '''.format(n_clicks, input1, input2)


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

In this example, changing text in the dcc.Input boxes won’t fire
the callback but clicking on the button will. The current values of
the dcc.Input values are still passed into the callback even though
they don’t trigger the callback function itself.

Note that we’re triggering the callback by listening to the
n_clicks property of the html.Button component. n_clicks is a
property that gets incremented every time the component has been
clicked on. It is available in every component in the
dash_html_components library.

Summary

We’ve covered the fundamentals of callbacks in Dash.
Dash apps are built off of a set
of simple but powerful principles: declarative UIs that are customizable
through reactive and functional Python callbacks.
Every element attribute of the declarative components can be updated
through a callback and a subset of the attributes, like the value
properties of the dcc.Dropdown, are editable by the user in the
interface.

The next part of the Dash tutorial covers interactive graphing.

Dash Tutorial Part 4: Interactive Graphing