Dash 3 for Component Developers

This page outlines changes in Dash 3.0 and what updates need to be made to component libraries to make them Dash 3.0-compatible. Dash 3.0 is currently available as a release candidate. Install it with pip install dash==3.0.0rc1

React Version Changes

The default version of React used in Dash 3.0 is React 18.3.1. If your components use features of React that are removed or deprecated in 18.3.1, you may need to make some updates. See the React 18 Upgrade Guide for full details. Some notable changes include:
- ReactDOM.render is no longer supported
- ReactDOM.findDOMNode is deprecated.
- defaultProps for function components is deprecated. See the next section for more details.

Default Props

Using defaultProps for function components has been deprecated in React and will show a warning in the console in Dash 3.0:

Support for defaultProps will be removed from function components in a future major release. Use JavaScript default parameters instead.

To prevent the warning from displaying in the console, you’ll need to use JavaScript default parameters instead and rebuild the components with the Dash 3 component generator.

Here’s an example of a component using defaultProps followed by an example using JavaScript default parameters:

const Tab = ({children}) => &lt;Fragment&gt;{children}&lt;Fragment&gt;;

Tab.defaultProps = {
    disabled: false,
    disabled_style: {
        color: '#d6d6d6',
    },
};

const Tab = ({
    children,
    disabled = false,
    disabled_style = {color: '#d6d6d6'},
}) => &lt;Fragment&gt;{children}&lt;Fragment&gt;;

For persistence props previously defined in defaultProps, you will need to update them to use Component.dashPersistence for them to continue to work. The following example shows how to make persistence props compatible with Dash 2 and 3. In this example defaultProps is used for React versions earlier than 18.3, and dashPersistence for later versions.

if (parseFloat(React.version.substring(0, React.version.lastIndexOf('.'))) < 18.3) {
    ExampleComponent.defaultProps = {
        persisted_props: ["value"],
        persistence_type: "local"

    };
} else {
    ExampleComponent.dashPersistence = {
        persisted_props: ['value'],
        persistence_type: 'local'
    };
}

Typing on Components

Dash 3.0 adds typing support to the Dash component generator, meaning components built with Dash 3.0 and later will include types on the component’s __init__ method.

For TypeScript components, the Dash component generator creates a proptypes.js file that needs to be added to the Dash package’s _js_dist in __init__.py:

_js_dist = [
...
"dev_package_path": "proptypes.js",
"namespace": "package"
...
]

`loading_state` Prop Removed

In versions of Dash prior to 3.0, Dash passed information about the loading state of components as a prop called loading_state and components could use this internally.

The loading_state property has been removed in Dash 3.0, which introduces a new API for accessing loading state of a component from the Dash context.

`useLoading` and `isLoading`

In a function component, use useLoading from the DashContext to check the component’s loading state. useLoading returns true when the component is loading and false when it is no longer loading. It rerenders the component when the loading state changes:

const ctx = window.dash_component_api.useDashContext();
const loading = ctx.useLoading();

if (loading) {
    // logic for when component is in a loading state
}

In a class component, use isLoading from the DashContext to check the component’s loading state. isLoading returns true when the component is loading and false when it is no longer loading, but doesn’t rerender the component. Use it within an async function that waits while the component is loading:

static contextType = window.dash_component_api.DashContext;

async loading() {
    while (this.context.isLoading()) {
        await wait(100);
    }
}

For compatibility with earlier versions of Dash, you can use the dash_component_api when it is available (Dash version 3 or later) or fallback to the loading_state prop when dash_component_api isn’t available.

export default function LoadingDiv({children, loading_state, ...props}) {
    let loading;
    if (window.dash_component_api) {
        const ctx = window.dash_component_api.useDashContext();
        loading = ctx.useLoading();
    } else {
        loading = loading_state?.is_loading;
    }
}

`useLoading` and `isLoading` Additional Options

useLoading and isLoading support extra options, provided as an object as the first argument, to configure what loading state is returned.

Use rawPath to get the loading state of a component by passing the full path. For example, this example gets the loading state of the first child component:

const ctx = window.dash_component_api.useDashContext();
const isLoading = ctx.useLoading({rawPath: children[0].props.componentPath});

Pass an extraPath to concatenate to the current component path to check a loading state of a specific child component. For example, if the current component’s path is [ 0 ] the following would check the loading state of the path [ 0, "props", "children", 0 ]

const ctx = window.dash_component_api.useDashContext();
const isLoading = ctx.useLoading({extraPath: ["props", "children", 0]});

Pass a function using filterFunc to check if specific props are loading. In the following example, the filterFunc passed to useLoading is used to check if the data prop of the current component is in a loading state:

const ctx = window.dash_component_api.useDashContext();
const isLoading = ctx.useLoading({
        filterFunc: loading =>
            loading.property === 'data'
    });

`_dashprivate` Props Removed

The following _dashprivate props used internally by Dash have been removed:
_dashprivate_layout, _dashprivate_loadingState, _dashprivate_loadingStateHash, and _dashprivate_path.

_dashprivate_layout Alternative

If you used _dashprivate_layout to access the props, prop types, or namespace of children passed to a component, you can get this info in Dash 3.0 and later using window.dash_component_api.getLayout by passing a component path (which can be accessed at <child>.props.componentPath):

window.dash_component_api.getLayout(children[0].props.componentPath);

For setting props, window.dash_clientside.set_props now accepts a path as well as an ID, so you can set props directly on a component at a given path. For example:

window.dash_clientside.set_props(children[0].props.componentPath, {value: 'new value'});

`dash.development.component_loader` Removed

dash.development.component_loader, which loaded components dynamically at runtime with dash.development.component_loader.load_components, has been removed. If you use this in your components, you’ll need to remove it and instead use the Dash component generator CLI, dash-generate-components. Run dash-generate-components --help for documentation.

Documentation and Test Updates

Dash 3.0 also introduces changes that impact writing Dash app code, for example, Dash.run_server has been removed and Dash.run should now be used. If you have docs examples or tests that use any of the removed features, you may need to make updates. See the Dash 3.0 migration guide for more details.

Dash Hooks

Dash 3.0 introduces a new hooks feature for writing plugins. See the Writing Dash Plugins using Dash Hooks page for a guide to creating pip-installable plugins that work with Dash apps.