New features for dcc.Loading #2760

AnnMarieW · 2024-02-15T17:00:54Z

This PR adds features to dcc.Loading

adds delay_show and delay_hide props to prevent flickering when the loading spinner shows only for a short time. (same as in the Dash Bootstrap Components dbc.Spinner)
adds overlay_style prop so you can do things like make children visible during loading and add opacity.
adds target_components prop to specify which component/props can trigger the loading spinner
adds custom_spinner prop so you can provide your own spinner rather than using the built-in options
adds display prop to override the loading status. Can set to "show", "hide", or "auto"
refactored component to functional instead of a class

Closes:
#951
#2147 will be fixed by using delay_show
#1922 will be fixed by using target_components
#1802 will be fixed by using delay_show
#2422 will be fixed by using delay_show
#879 will be possible by using custom_spinner and overlay_style
#736. can't replicate the issue

Closes from the old dcc repo
plotly/dash-core-components#873 - possible with custom_spinner and delay_show
#1541 - can't replicate the issue
plotly/dash-core-components#709 - possible with target_components

Contributor Checklist

Example 1 `delay_hide` and `delay_show` prop

The delay_hide and delay_show props can be used to prevent flickering when the loading spinner shows only for a short time.

This callback runs for 500ms. This example shows how to:

prevent the spinner from showing by setting delay_show=700.
make the spinner show for a minimum amount of time by setting delay_hide=2000

A good use-case for delay_show is when hoverData is used in a callback. A good demo is this cross filter example in the docs Try wrapping the app layout with dcc.Loading([<example app layout> ], delay_show=500)

import time

import dash
from dash import Dash, Input, Output, State, html, dcc

app=Dash()
app.layout = html.Div(
    [
        html.Button("Load", id="loading-button", n_clicks=0),
        html.Div("delay_show (ms)"),
        dcc.Input(type="number", value=0, id="delay-show", debounce=True),
        html.Div("delay_hide (ms)"),
        dcc.Input(type="number", value=0, id="delay-hide", debounce=True),
        html.Hr(),
        dcc.Loading(html.Div(id="loading-output"), id="loading"),
    ]
)


@app.callback(
    Output("loading-output", "children"),
    Input("loading-button", "n_clicks"),
)
def load_output(n):
    if n:
        time.sleep(.5)
        return f"Output loaded {n} times"
    return "Output not reloaded yet"

@app.callback(
    Output("loading", "delay_show"),
    Output("loading", "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 dash.no_update
    return int(show), int(hide)

app.run(debug=True)

Example 2 `target_components` prop

Use the target_components prop to specify which component/props can trigger the loading spinner.
By default, Loading fires when any child element enters loading state. This makes loading opt-in: Loading animation only enabled when one of target components/props enters loading state.

target_components is a dict where the key is the component id, and the value is the prop name | list of prop names | "*"

examples - the following will trigger the loading spinner:

Any prop in the "grid" component

target_components ={"grid": "*"}

Either the grid's rowData or columnDefs

target_components ={"grid": ["rowData", "columnDefs"]}

Only the grid's rowData

target_components ={"grid": "rowData"}

import time

import dash
from dash import Dash, Input, Output, State, html, dcc

app=Dash()
app.layout = html.Div(
    [
        html.Button("Load div 1", id="loading-button1", n_clicks=0),
        html.Button("Load div 2", id="loading-button2", n_clicks=0),
        html.Hr(),
        dcc.Loading([
            html.Div(id="loading-output1"),
            html.Div(id="loading-output2"),
        ], target_components={"loading-output1": "children"}),
    ]
)


@app.callback(
    Output("loading-output1", "children"),
    Input("loading-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-output2", "children"),
    Input("loading-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)

Example 3 Styling with `overlay_style` prop

Default: content is hidden while loading

Styled with `overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"}`

This keeps the content visible while loading and adds opacity

import time

import dash
from dash import Dash, Input, Output, State, html, dcc
import plotly.express as px
data_canada = px.data.gapminder().query("country == 'Canada'")
app=Dash()
app.layout = html.Div(
    [
        html.Button("Start", id="loading-button", n_clicks=0),
        html.Hr(),
        dcc.Loading(
            [dcc.Graph(id="loading-output", figure=px.line(data_canada, x="year", y="pop"))],
            overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"},
            color="red"
        ),
    ]
)


@app.callback(
    Output("loading-output", "figure"),
    Input("loading-button", "n_clicks"),
)
def load_output(n):
    if n:
        time.sleep(1)
        return px.bar(data_canada, x="year", y="pop")
    return dash.no_update


app.run(debug=True)

Example 4 `custom_spinner` prop

Instead of using one of the built-in spinner component, you can provide your own.

A custom_spinner can be used to remove/hide the spinner. This is a convenient way to remove the spinner when using nested dcc.Loading components.
It's possible to create a component with custom loading messages using any Dash components.

This example uses:

custom_spinner=html.H2(["My Custom Spinner", dbc.Spinner(color="danger")])

import time

import dash
from dash import Dash, Input, Output, State, html, dcc
import plotly.express as px
import dash_bootstrap_components as dbc

data_canada = px.data.gapminder().query("country == 'Canada'")

app=Dash(external_stylesheets=[dbc.themes.BOOTSTRAP])
app.layout = dbc.Container(
    [
        dbc.Button("Start", id="loading-button", n_clicks=0),
        html.Hr(),
        dcc.Loading(
            [dcc.Graph(id="loading-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")])
        ),
    ]
)


@app.callback(
    Output("loading-output", "figure"),
    Input("loading-button", "n_clicks"),
)
def load_output(n):
    if n:
        time.sleep(1)
        return px.bar(data_canada, x="year", y="pop")
    return dash.no_update


app.run(debug=True)

Example 5 `display` prop

Use the display prop to manually display or hide the loading spinner. Set to "show", "hide" or "auto"(the default)

import time

import dash
from dash import Dash, Input, Output, State, html, dcc


app=Dash()
app.layout = html.Div(
    [
        html.Div("Select mode"),
        html.Button("Start", id="loading-button", n_clicks=0),
        dcc.Dropdown(["auto", "show", "hide"], value="auto", id="display", style={"marginBottom": 100}),
        html.Hr(),
        dcc.Loading(
            html.Div("Demo of manually controlling  loading status", id="loading-output"),
            id="loading"


        ),
    ]
)

@app.callback(
    Output("loading", "display"),
    Input("display", "value")
)
def update_display(display):
    return display


@app.callback(
    Output("loading-output", "children"),
    Input("loading-button", "n_clicks"),
)
def load_output(n):
    if n:
        time.sleep(5)
        return f"Updated content {n}"
    return dash.no_update


app.run(debug=True)

components/dash-core-components/src/components/Loading.react.js

JamesKunstle · 2024-02-15T18:43:39Z

@AnnMarieW Could you give an example of when target_component is used?

delay_show and delay_hide seem reasonable and the implementation makes sense to me.

components/dash-core-components/src/components/Loading.react.js

JamesKunstle · 2024-02-16T15:07:58Z

@AnnMarieW This is really exciting, the loading opacity update is really clever, and the demonstrations are really helpful to understand the scope of these updates.

JamesKunstle · 2024-02-19T19:40:40Z

@AnnMarieW re: 'mode' prop-

What you implemented matches the Loading behavior that I'd like to have.

I'd consider changing the name, however. 'mode' seems like a execution context rather than 'on or off.' I'd perhaps use 'mode' to be 'auto' or 'manual' and 'manual' would disable targeted loading state and consideration of the loading state of children, and instead would rely on another prop like 'setLoading' or something.

This would clarify that the Loading component is either driven by state that can be inferred from the renderer (those components whose state are waiting for backend information) or directly specified by the user (indirectly related components, like a search option that should be put into a loading state while something else is executing).

AnnMarieW · 2024-02-19T19:53:16Z

@JamesKunstle I'm not sure what you mean re the mode prop. Can you clarify or supply some code?

JamesKunstle · 2024-02-19T22:28:01Z

@AnnMarieW
Yes certainly:

So mode prop could just be manual-mode and be a boolean, True or False.

When not in manual-mode, the Loading component behaves exactly as it does now, changing as an effect of other components waiting on a response from the backend.

In manual mode, the Loading component would honor the additional prop set-loading (naming not final), a boolean that would be under full manual control from the user.

        if (manual_mode) {
            setShowSpinner(set_loading);
            return;
        }

Here's a concrete example:

Imagine that I have a dcc.Interval component that fires every 5 seconds, making a request to the backend to check whether an asynchronous resource is available. Another component, like a Dropdown, indirectly relies on the availability of that resource, so it should be in a forced Loading state that stays enabled even when the dcc.Interval is waiting to fire again.

If I could use manual mode, a final successful return from the callback that handles the Interval logic could disable loading for the Dropdown.

This way, Loading becomes a developer-controllable state that is managed by application logic rather than by the dash renderer.

ndrezn · 2024-02-26T15:00:01Z

components/dash-core-components/src/components/Loading.react.js

+    const hiddenContainer = mergeRight(
+        {visibility: 'hidden', position: 'relative'},
+        overlay_style
+    );


overlay_style to set dcc.Loading to be semi-translucent feels like a really common use case. I wonder if it's worth adding a prop like opacity to specify explicitly with some default styles applied?

This way developers don't need to remember the more complex e.g. overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"} if they just want to make the overlay translucent?

I thought about that, but I expect most people would tweak the opacity and background color depending on the theme (light/dark). Or do know some CSS that would work in most cases?

Could probably pick a neutral grey? I've found #7F8487 is a good middle ground grey that works well in light and dark.

I can try that - but still want to give the ability for people to use any CSS in overlay_style. Are you suggesting another prop, perhaps that sets {"visibility":"visible", "opacity": .5, "backgroundColor": "#7F8487"}?
Then what if people set both props?

If there are a couple examples in the docs, it might work OK to just leave it as-is?

Yeah, maybe let's leave as-is for now with good examples in the docs, and see if there is community feedback from there?

alexcjohnson · 2024-02-26T20:51:36Z

components/dash-core-components/src/components/Loading.react.js

+     * example: `[{"output-container": "children"}]`
+     *
+     */
+    target_components: PropTypes.arrayOf(PropTypes.object),


I wonder if this would be better as

objectOf(arrayOf(string))

or perhaps

objectOf(oneOfType([string, arrayOf(string)]))

so you could do something like:

target_components={"my_table": ["data", "columns"], "my_dropdown": "options"}

I added this, plus it's possible to use a wildcard. This will trigger loading for any prop in the "my_table" component

target_components={"my_table": "*", "my_dropdown": "options"}

alexcjohnson · 2024-02-26T23:30:03Z

re: mode - agreed that the name is a little ambiguous, but I do like having a single prop with three values, rather than a second prop that only applies to one of the values of the other.

What about borrowing from CSS: display: "show" | "hide" | "auto"?

emilykl · 2024-02-27T16:18:00Z

Re: api for enabling/disabling, what feels most intuitive to me is disabled for consistency with dcc.Interval and the input components, and also it's a more transparent name -- doesn't lend itself super easily to 3 values though.

JamesKunstle · 2024-02-28T15:58:32Z

Re: api for enabling/disabling, what feels most intuitive to me is disabled for consistency with dcc.Interval and the input components, and also it's a more transparent name -- doesn't lend itself super easily to 3 values though.

That, for me, feels ergonomically less nice for the same reason that it does for dcc.Interval - negating 'disabled' in my head to set the correct boolean value takes a few more cycles than I want, and I normally create global variables to solve it, like "INTERVAL_DISABLED" = True, "INTERVAL_ENABLED" = False, etc.

re: mode - agreed that the name is a little ambiguous, but I do like having a single prop with three values, rather than a second prop that only applies to one of the values of the other.

What about borrowing from CSS: display: "show" | "hide" | "auto"?

Passing a string parameter for 'display' seems reasonable

alexcjohnson · 2024-02-29T03:29:57Z

Ok great, let’s go with display: "show" | "hide" | "auto"

AnnMarieW · 2024-02-29T13:30:17Z

Ok great, let’s go with display: "show" | "hide" | "auto"

Done

ndrezn

💃 Super excited about these changes. I think it'd be nice to have a dedicated opacity prop but I understand concerns about color... so I don't feel super strongly about this, as long as it's well-documented.

On that note... is there a corresponding docs PR?

AnnMarieW · 2024-03-04T16:05:55Z

I can work on the docs PR next.
Note that I can't merge PRs here, so can you do that for me?

emilykl · 2024-03-04T16:13:51Z

Super excited for these!

T4rk1n · 2024-03-04T16:35:17Z

I can work on the docs PR next.
Note that I can't merge PRs here, so can you do that for me?

Can we hold on merging while I work on a fix for #2775

…dcc-loading

T4rk1n

💃

AnnMarieW · 2024-03-21T18:14:43Z

Here's the PR for the docs https://github.com/plotly/ddk-dash-docs/pull/2570

schultz77 · 2024-04-08T07:54:53Z

Hello AnnMarieW,

thank you very much for implementing the features delay_show and delay_hide to dcc.Loading.
Do I have to update dash to have access to it?

Thank You very much in Advance

TypeError: The dcc.Loading component (version 2.14.1) received an unexpected keyword argument: delay_show
Allowed arguments: children, className, color, debug, fullscreen, id, loading_state, parent_className, parent_style, style, type

dash==2.14.1
dash-bootstrap-components==1.5.0
dash-core-components==2.0.0

After updating dash:
TypeError: The dcc.Loading component (version 2.16.1) received an unexpected keyword argument: delay_show
Allowed arguments: children, className, color, debug, fullscreen, id, loading_state, parent_className, parent_style, style, type

AnnMarieW · 2024-04-08T12:39:12Z

Hi @schultz77

Thanks! I’m looking forward to it too 🙂. This will be available in the next release (Dash 2.17)

schultz77 · 2024-04-08T13:37:26Z

Ok! Thank You for your quick reply. In the meantime I'll keep using dbc.Spinner...

New features for dcc.Loading

27c3498

AnnMarieW requested a review from alexcjohnson as a code owner February 15, 2024 17:00

AnnMarieW marked this pull request as draft February 15, 2024 17:20

JamesKunstle reviewed Feb 15, 2024

View reviewed changes

components/dash-core-components/src/components/Loading.react.js Outdated Show resolved Hide resolved

JamesKunstle reviewed Feb 15, 2024

View reviewed changes

components/dash-core-components/src/components/Loading.react.js Show resolved Hide resolved

JamesKunstle reviewed Feb 15, 2024

View reviewed changes

components/dash-core-components/src/components/Loading.react.js Outdated Show resolved Hide resolved

JamesKunstle reviewed Feb 15, 2024

View reviewed changes

components/dash-core-components/src/components/Loading.react.js Show resolved Hide resolved

Added overlay_style prop removed opacity and backgroundColor props

b5b9710

This was referenced Feb 16, 2024

Loading state not working correctly when layout is in a function #736

Closed

Loading states on chained callbacks (grandchildren) #1541

Closed

AnnMarieW marked this pull request as ready for review February 16, 2024 23:41

AnnMarieW and others added 3 commits February 18, 2024 11:45

update doc strings

d87be76

add the mode prop for manual override of loading state

872e8a7

Merge branch 'dev' into update-dcc-loading

840b322

ndrezn reviewed Feb 26, 2024

View reviewed changes

alexcjohnson reviewed Feb 26, 2024

View reviewed changes

refactored target_components prop

2f0ab2d

changed prop name from mode to display

2c0961a

AnnMarieW added 2 commits February 29, 2024 05:47

Merge branch 'dev' into update-dcc-loading

e710b47

Merge branch 'dev' into update-dcc-loading

0f3a65c

AnnMarieW added 2 commits March 3, 2024 15:24

added tests

4edbe55

added changelog

d1c0a7f

ndrezn approved these changes Mar 4, 2024

View reviewed changes

Merge branch 'dev' into update-dcc-loading

eda25eb

AnnMarieW requested a review from T4rk1n as a code owner March 4, 2024 16:30

AnnMarieW and others added 3 commits March 4, 2024 10:27

fixed typo in test

d62a037

Merge remote-tracking branch 'origin/update-dcc-loading' into update-…

5aaef7d

…dcc-loading

Merge branch 'dev' into update-dcc-loading

79a01d8

T4rk1n approved these changes Mar 7, 2024

View reviewed changes

ndrezn merged commit 78ebf0d into plotly:dev Mar 8, 2024
3 checks passed

antonymilne mentioned this pull request May 21, 2024

[Feat] Add new dcc.Loading features in dash 2.17 mckinsey/vizro#487

Merged

1 task

AnnMarieW mentioned this pull request Jun 3, 2024

[Feature Request] Make dcc.Loading toggle-able attribute for enabled/disabled #2696

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New features for dcc.Loading #2760

New features for dcc.Loading #2760

AnnMarieW commented Feb 15, 2024 •

edited

Loading

JamesKunstle commented Feb 15, 2024

JamesKunstle commented Feb 16, 2024

JamesKunstle commented Feb 19, 2024

AnnMarieW commented Feb 19, 2024

JamesKunstle commented Feb 19, 2024 •

edited

Loading

ndrezn Feb 26, 2024

AnnMarieW Feb 26, 2024 •

edited

Loading

ndrezn Mar 4, 2024 •

edited

Loading

AnnMarieW Mar 4, 2024

ndrezn Mar 4, 2024

alexcjohnson Feb 26, 2024

AnnMarieW Feb 27, 2024

alexcjohnson commented Feb 26, 2024

emilykl commented Feb 27, 2024

JamesKunstle commented Feb 28, 2024

alexcjohnson commented Feb 29, 2024

AnnMarieW commented Feb 29, 2024

ndrezn left a comment

AnnMarieW commented Mar 4, 2024

emilykl commented Mar 4, 2024

T4rk1n commented Mar 4, 2024

T4rk1n left a comment

AnnMarieW commented Mar 21, 2024

schultz77 commented Apr 8, 2024 •

edited

Loading

AnnMarieW commented Apr 8, 2024

schultz77 commented Apr 8, 2024

New features for dcc.Loading #2760

New features for dcc.Loading #2760

Conversation

AnnMarieW commented Feb 15, 2024 • edited Loading

Contributor Checklist

Example 1 delay_hide and delay_show prop

Example 2 target_components prop

Example 3 Styling with overlay_style prop

Default: content is hidden while loading

Styled with overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"}

Example 4 custom_spinner prop

Example 5 display prop

JamesKunstle commented Feb 15, 2024

JamesKunstle commented Feb 16, 2024

JamesKunstle commented Feb 19, 2024

AnnMarieW commented Feb 19, 2024

JamesKunstle commented Feb 19, 2024 • edited Loading

ndrezn Feb 26, 2024

Choose a reason for hiding this comment

AnnMarieW Feb 26, 2024 • edited Loading

Choose a reason for hiding this comment

ndrezn Mar 4, 2024 • edited Loading

Choose a reason for hiding this comment

AnnMarieW Mar 4, 2024

Choose a reason for hiding this comment

ndrezn Mar 4, 2024

Choose a reason for hiding this comment

alexcjohnson Feb 26, 2024

Choose a reason for hiding this comment

AnnMarieW Feb 27, 2024

Choose a reason for hiding this comment

alexcjohnson commented Feb 26, 2024

emilykl commented Feb 27, 2024

JamesKunstle commented Feb 28, 2024

alexcjohnson commented Feb 29, 2024

AnnMarieW commented Feb 29, 2024

ndrezn left a comment

Choose a reason for hiding this comment

AnnMarieW commented Mar 4, 2024

emilykl commented Mar 4, 2024

T4rk1n commented Mar 4, 2024

T4rk1n left a comment

Choose a reason for hiding this comment

AnnMarieW commented Mar 21, 2024

schultz77 commented Apr 8, 2024 • edited Loading

AnnMarieW commented Apr 8, 2024

schultz77 commented Apr 8, 2024

AnnMarieW commented Feb 15, 2024 •

edited

Loading

Example 1 `delay_hide` and `delay_show` prop

Example 2 `target_components` prop

Example 3 Styling with `overlay_style` prop

Styled with `overlay_style={"visibility":"visible", "opacity": .5, "backgroundColor": "white"}`

Example 4 `custom_spinner` prop

Example 5 `display` prop

JamesKunstle commented Feb 19, 2024 •

edited

Loading

AnnMarieW Feb 26, 2024 •

edited

Loading

ndrezn Mar 4, 2024 •

edited

Loading

schultz77 commented Apr 8, 2024 •

edited

Loading