dcc.Loading
The dcc.Loading component displays a customizable loading spinner until the wrapped component has rendered.
Examples
Basic Loading
Here’s a simple example where the Loading component wraps the outputs for a couple of Input components.
- The callback for the first
Inputdemonstrates the basic usage with a default spinner component. - The callback for the second
Inputshows how even nested children will set the loading state of the wrapped component. - There are 5 built-in spinner types. The
dcc.Loadingthat wraps the secondInputusestype="circle"
```python
from dash import Dash, dcc, html, Input, Output, callback
import time
app = Dash()
app.layout = html.Div([
html.H3("Edit text input to see loading state"),
html.Div("Input triggers local spinner"),
dcc.Input(id="loading-input-1"),
dcc.Loading(
id="loading-1",
type="default",
children=html.Div(id="loading-output-1")
),
html.Div([
html.Div('Input triggers nested spinner'),
dcc.Input(id="loading-input-2"),
dcc.Loading(
id="loading-2",
children=[html.Div([html.Div(id="loading-output-2")])],
type="circle",
)
]),
])
@callback(Output("loading-output-1", "children"), Input("loading-input-1", "value"))
def input_triggers_spinner(value):
time.sleep(1)
return value
@callback(Output("loading-output-2", "children"), Input("loading-input-2", "value"))
def input_triggers_nested(value):
time.sleep(1)
return value
if __name__ == "__main__":
app.run(debug=False)
```
Delay Show and Delay Hide
To prevent the spinner from quickly flashing during rapid loading times, adjust the delay_show and delay_hide properties.
delay_show: time delay (in ms) after the wrapped components enter the loading state and before the spinner is shown.
delay_hide: the minimum time (in ms) the spinner is displayed after it’s shown.
In this example, the callback takes about 100 milliseconds.
Try the following:
- Press the Load button with both delays at 0. Notice the spinner briefly appearing.
- To prevent showing the spinner, increase delay_show to 500
- To extend the time the spinner is visible, increase delay_hide to 500 or more and set delay_show to 0.
```python
import time
from dash import Dash, Input, Output, callback, html, dcc, no_update
app = Dash()
app.layout = html.Div(
[
html.Label("Set delay_show time (ms)"),
dcc.Input(type="number", value=0, id="delay-show", debounce=True),
html.Label("Set delay_hide time (ms)"),
dcc.Input(type="number", value=0, id="delay-hide", debounce=True),
html.Hr(),
html.Button("Load", id="loading-delay-button", n_clicks=0),
dcc.Loading(html.Div(id="loading-delay-output"), id="loading-component"),
]
)
@callback(
Output("loading-delay-output", "children"),
Input("loading-delay-button", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(.1)
return f"Output loaded {n} times"
return "Output not reloaded yet"
@callback(
Output("loading-component", "delay_show"),
Output("loading-component", "delay_hide"),
Input("delay-show", "value"),
Input("delay-hide", "value")
)
def update_delay_show_hide(show, hide):
if show is None or hide is None:
return no_update
return int(show), int(hide)
app.run(debug=True)
```
Loading Overlay Style
By default, the spinner hides the wrapped component during loading. To make the wrapped component visible and blur the
content, you can set the following CSS in the overlay_style prop:
dcc.Loading(
overlay_style={"visibility":"visible", "filter": "blur(2px)"},
# other properties
)
```python
import time
from dash import Dash, Input, Output, callback, html, dcc, no_update
import dash_bootstrap_components as dbc
app = Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
app.layout = dbc.Container(
[
dbc.Button("Start", id="loading-overlay-button", n_clicks=0),
dcc.Loading(
[dbc.Alert("My Data", id="loading-overlay-output", className="h4 p-4 mt-3")],
overlay_style={"visibility":"visible", "filter": "blur(2px)"},
type="circle",
),
]
)
@callback(
Output("loading-overlay-output", "children"),
Input("loading-overlay-button", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(1)
return f"Data updated {n} times."
return no_update
if __name__ == "__main__":
app.run(debug=True)
```
Custom Spinner Component
Instead of using one of the built-in spinners, you can use a Dash component as the spinner. This example sets the
custom_spinner property to a component that includes a spinner from the Dash Bootstrap Components library, but you can use
any components to set the custom_spinner prop.
Note that the type, fullscreen, debug, color, style and className properties are specific to the built-in spinner types and do
not work with custom spinner components.
-
```python
import time
from dash import Dash, Input, Output, callback, html, dcc, no_update
import plotly.express as px
import dash_bootstrap_components as dbc
data_canada = px.data.gapminder().query("country == 'Canada'")
app = Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
app.layout = dbc.Container(
[
dbc.Button("Start", id="custom-spinner-button", n_clicks=0),
html.Hr(),
dcc.Loading(
[dcc.Graph(id="custom-spinner-output", figure=px.line(data_canada, x="year", y="pop"))],
overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"},
custom_spinner=html.H2(["My Custom Spinner", dbc.Spinner(color="danger")]),
),
]
)
@callback(
Output("custom-spinner-output", "figure"),
Input("custom-spinner-button", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(1)
return px.bar(data_canada, x="year", y="pop")
return no_update
if __name__ == "__main__":
app.run(debug=True)
```
Target Components
Use the target_components property to specify which component id and component property combinations it wraps can trigger the
loading spinner. The spinner component is displayed only when one of the target component and properties enters
loading state.
target_components is a dictionary where the key is the component id, and the value is the property name, or a list of property names or “*”
For example, this will display the spinner only when the AgGrid’s rowData property is being updated.
app.layout=dcc.Loading(
html.Div([
dag.AgGrid(id="grid"),
html.Div(id="output-div")
]),
target_components={"grid": "rowData" }
)
This will display the spinner while any of the grid’s properties are being updated:
target_components ={"grid": "*"}
This will display the spinner when either the grid’s rowData or columnDefs are being updated:
target_components ={"grid": ["rowData", "columnDefs"]}
In this example, the dcc.Loading component wraps two callback outputs, but only one triggers the spinner.
```python
import time
from dash import Dash, Input, Output, callback, html, dcc
app = Dash()
app.layout = html.Div(
[
html.Button("Load div 1", id="loading-target-button1", n_clicks=0),
html.Button("Load div 2", id="loading-target-button2", n_clicks=0),
html.Hr(),
dcc.Loading([
html.Div(id="loading-target-output1"),
html.Div(id="loading-target-output2"),
], target_components={"loading-target-output1": "children"}),
]
)
@callback(
Output("loading-target-output1", "children"),
Input("loading-target-button1", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(2)
return f"Output loaded {n} times. This callback triggers the loading spinner"
return "Callback 1 output not reloaded yet"
@app.callback(
Output("loading-target-output2", "children"),
Input("loading-target-button2", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(.5)
return f"Output loaded {n} times. No loading spinner"
return "Callback 2 output not reloaded yet"
app.run(debug=True)
```
Manually Display Loading Spinner
Use the display property to manually display or hide the loading spinner. Set to “show”, “hide” or “auto” (the default).
```python
import time
from dash import Dash, Input, Output, callback, html, dcc, no_update
app = Dash()
app.layout = html.Div(
[
html.Div("Select mode"),
html.Button("Start", id="loading-display-button", n_clicks=0),
dcc.Dropdown(["auto", "show", "hide"], value="auto", id="dd-display", clearable=False, style={"marginBottom": 50}),
dcc.Loading(
html.Div("Demo of manually controlling loading status", id="loading-display-output"),
id="loading-display"
),
]
)
@callback(
Output("loading-display", "display"),
Input("dd-display", "value")
)
def update_display(display):
return display
@app.callback(
Output("loading-display-output", "children"),
Input("loading-display-button", "n_clicks"),
)
def load_output(n):
if n:
time.sleep(5)
return f"Updated content {n}"
return no_update
app.run(debug=True)
```
Please also check out this section on loading states if you want a more customizable experience.
Limitations
Updating component properties with set_props in a callback does not update the loading state and is not compatible with the dcc.Loading component.
Loading Properties
Access this documentation in your Python terminal with:
```pythonhelp(dash.dcc.Loading)
```
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.
children (list of list of or a singular dash component, string or numbers | list of or a singular dash component, string or number; optional):
Array that holds components to render.
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.
type (a value equal to: ‘graph’, ‘cube’, ‘circle’, ‘dot’ or ‘default’; optional):
Property that determines which built-in spinner to show one of
‘graph’, ‘cube’, ‘circle’, ‘dot’, or ‘default’.
fullscreen (boolean; optional):
Boolean that makes the built-in spinner display full-screen.
debug (boolean; optional):
If True, the built-in spinner will display the component_name and
prop_name while loading.
className (string; optional):
Additional CSS class for the built-in spinner root DOM node.
parent_className (string; optional):
Additional CSS class for the outermost dcc.Loading parent div DOM node.
style (dict; optional):
Additional CSS styling for the built-in spinner root DOM node.
parent_style (dict; optional):
Additional CSS styling for the outermost dcc.Loading parent div DOM
node.
overlay_style (dict; optional):
Additional CSS styling for the spinner overlay. This is applied to the
dcc.Loading children while the spinner is active. The default is
{'visibility': 'hidden'}.
color (string; default '#119DFF'):
Primary color used for the built-in loading spinners.
display (a value equal to: ‘auto’, ‘show’ or ‘hide’; default 'auto'):
Setting display to “show” or “hide” will override the loading state
coming from dash-renderer.
delay_hide (number; default 0):
Add a time delay (in ms) to the spinner being removed to prevent
flickering.
delay_show (number; default 0):
Add a time delay (in ms) to the spinner being shown after the
loading_state is set to True.
show_initially (boolean; default True):
Whether the Spinner should show on app start-up before the loading
state has been determined. Default True. Use when also setting
delay_show.
target_components (dict with strings as keys and values of type string | list of strings; optional):
Specify component and prop to trigger showing the loading spinner
example: {"output-container": "children", "grid": \["rowData",
"columnDefs\]}.
custom_spinner (list of or a singular dash component, string or number; optional):
Component to use rather than the built-in spinner specified in the
type prop.