Dmc Py

Dash Mantine Components (DMC) v2.x

Build modern Dash applications with 100+ Mantine UI components.

Quick Start

Minimal DMC app requiring MantineProvider wrapper:

from dash import Dash, callback, Input, Output
import dash_mantine_components as dmc

app = Dash(__name__)

app.layout = dmc.MantineProvider([
    dmc.Container([
        dmc.Title("My DMC App", order=1),
        dmc.TextInput(label="Name", id="name-input", placeholder="Enter name"),
        dmc.Button("Submit", id="submit-btn", mt="md"),
        dmc.Text(id="output", mt="md"),
    ], size="sm", py="xl")
])

@callback(Output("output", "children"), Input("submit-btn", "n_clicks"), Input("name-input", "value"))
def update_output(n_clicks, name):
    if not n_clicks:
        return ""
    return f"Hello, {name or 'World'}!"

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

Critical: All DMC components MUST be inside dmc.MantineProvider.

Version Note: This skill targets DMC 2.x (Mantine 8.x). Run pip show dash-mantine-components to check your installed version. For the latest features and API changes, use fetch_docs.py to query the official documentation at https://www.dash-mantine-components.com/assets/llms.txt

---

Workflow Decision Tree

Select components by use case:

Form Inputs

Layout

Navigation

Feedback & Overlays

Data Display

Charts

What's New in Recent Versions

v2.5.x:

• TableOfContents - Auto-generated table of contents from headings
• selectFirstOptionOnDropdownOpen prop for Select/MultiSelect/Autocomplete
• openOnFocus prop for Combobox components
• AppShell mode="static" for nested shells
• window.MantineCore / window.MantineHooks for custom component building

v2.4.x:

• CopyButton / CustomCopyButton - Clipboard operations
• getEditor(id) - Access RichTextEditor TipTap instance in clientside callbacks
• Function props for chart axis/grid customization

v2.3.x:

• MiniCalendar - Compact calendar component
• ScrollAreaAutoheight - Auto-sizing scroll area
• DirectionProvider - RTL text direction support

→ Full component reference: references/components-quick-ref.md

---

Core Patterns

Theming

Configure theme via MantineProvider:

theme = {
    "primaryColor": "blue",
    "fontFamily": "Inter, sans-serif",
    "defaultRadius": "md",
    "colors": {
        "brand": ["#f0f9ff", "#e0f2fe", "#bae6fd", "#7dd3fc", "#38bdf8",
                  "#0ea5e9", "#0284c7", "#0369a1", "#075985", "#0c4a6e"]
    },
    "components": {
        "Button": {"defaultProps": {"size": "md", "radius": "md"}},
        "TextInput": {"defaultProps": {"size": "sm"}},
    }
}

app.layout = dmc.MantineProvider(
    theme=theme,
    forceColorScheme="light",  # or "dark", or None for auto
    children=[...]
)

Theme Toggle Pattern (clientside callback):

from dash import clientside_callback, ClientsideFunction

app.layout = dmc.MantineProvider(
    id="mantine-provider",
    children=[
        dcc.Store(id="theme-store", storage_type="local", data="light"),
        dmc.Switch(id="theme-switch", label="Dark mode", checked=False),
        # ... rest of layout
    ]
)

clientside_callback(
    """(checked) => checked ? "dark" : "light" """,
    Output("mantine-provider", "forceColorScheme"),
    Input("theme-switch", "checked"),
)

→ Full theming guide: references/theming-patterns.md

Styling

Style Props - Universal props on all DMC components:

Responsive Values - Dict with breakpoints:

dmc.Button("Click", w={"base": "100%", "sm": "auto", "lg": 200})
dmc.Stack(gap={"base": "xs", "md": "lg"})

Styles API - Target nested elements:

dmc.Select(
    data=["A", "B", "C"],
    classNames={"input": "my-input", "dropdown": "my-dropdown"},
    styles={"label": {"fontWeight": 700}, "input": {"borderColor": "blue"}},
)

→ Full styling guide: references/styling-guide.md

Callbacks

Basic Pattern:

from dash import callback, Input, Output, State

@callback(
    Output("output", "children"),
    Input("button", "n_clicks"),
    State("input", "value"),
    prevent_initial_call=True,
)
def update(n_clicks, value):
    return f"Clicked {n_clicks} times with value: {value}"

Pattern-Matching (dynamic components):

from dash import ALL, MATCH, callback_context as ctx

# ALL: Respond to any button with type "dynamic-btn"
@callback(
    Output("output", "children"),
    Input({"type": "dynamic-btn", "index": ALL}, "n_clicks"),
)
def handle_all(n_clicks_list):
    triggered = ctx.triggered_id  # {"type": "dynamic-btn", "index": X}
    return f"Button {triggered['index']} clicked"

# MATCH: Update the output matching the triggered input
@callback(
    Output({"type": "item-output", "index": MATCH}, "children"),
    Input({"type": "item-btn", "index": MATCH}, "n_clicks"),
    prevent_initial_call=True,
)
def handle_match(n):
    return f"Clicked {n} times"

Clientside Callback (browser-side JavaScript):

from dash import clientside_callback

clientside_callback(
    """(n) => n ? `Clicked ${n} times` : "Not clicked" """,
    Output("output", "children"),
    Input("button", "n_clicks"),
)

DMC-Specific Props:

• debounce=300 - Delay callback trigger (ms) for TextInput, Textarea
• persistence=True - Persist value across page reloads
• persistence_type="local" - Storage type: memory, local, session

→ Full callbacks reference: references/callbacks-advanced.md

---

Multi-Page Apps

Use Dash Pages with DMC AppShell:

# app.py
import dash
from dash import Dash
import dash_mantine_components as dmc

app = Dash(__name__, use_pages=True, pages_folder="pages")

app.layout = dmc.MantineProvider([
    dmc.AppShell(
        [
            dmc.AppShellHeader(dmc.Group([
                dmc.Title("My App", order=3),
                dmc.Switch(id="theme-switch"),
            ], h="100%", px="md")),
            dmc.AppShellNavbar([
                dmc.NavLink(label=page["name"], href=page["path"], active=page["path"] == "/")
                for page in dash.page_registry.values()
            ], p="md"),
            dmc.AppShellMain(dash.page_container),
        ],
        header={"height": 60},
        navbar={"width": 250, "breakpoint": "sm", "collapsed": {"mobile": True}},
        padding="md",
    )
])

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

# pages/home.py
import dash
import dash_mantine_components as dmc

dash.register_page(__name__, path="/", name="Home")

layout = dmc.Container([
    dmc.Title("Welcome", order=2),
    dmc.Text("Home page content"),
], py="xl")

# pages/analytics.py
import dash
import dash_mantine_components as dmc

dash.register_page(__name__, path="/analytics", name="Analytics")

layout = dmc.Container([
    dmc.Title("Analytics", order=2),
    # Charts, tables, etc.
], py="xl")

Variable Paths:

# pages/user.py
dash.register_page(__name__, path_template="/user/<user_id>")

def layout(user_id=None):
    return dmc.Container([
        dmc.Title(f"User: {user_id}", order=2),
    ])

→ Full multi-page guide: references/multi-page-apps.md

---

Component Categories

Quick links to reference documentation:

Asset Templates

Copy and adapt these templates:

Utility Scripts

---

Common Tasks

Form with Validation

@callback(
    Output("submit-btn", "disabled"),
    Output("error-text", "children"),
    Input("email-input", "value"),
    Input("password-input", "value"),
)
def validate_form(email, password):
    errors = []
    if not email or "@" not in email:
        errors.append("Valid email required")
    if not password or len(password) < 8:
        errors.append("Password must be 8+ characters")
    return bool(errors), ", ".join(errors)

Modal Open/Close

app.layout = dmc.MantineProvider([
    dmc.Button("Open Modal", id="open-modal-btn"),
    dmc.Modal(
        id="my-modal",
        title="Confirm Action",
        children=[
            dmc.Text("Are you sure?"),
            dmc.Group([
                dmc.Button("Cancel", id="cancel-btn", variant="outline"),
                dmc.Button("Confirm", id="confirm-btn", color="red"),
            ], justify="flex-end", mt="md"),
        ],
    ),
])

@callback(
    Output("my-modal", "opened"),
    Input("open-modal-btn", "n_clicks"),
    Input("cancel-btn", "n_clicks"),
    Input("confirm-btn", "n_clicks"),
    prevent_initial_call=True,
)
def toggle_modal(open_clicks, cancel, confirm):
    from dash import ctx
    if ctx.triggered_id == "open-modal-btn":
        return True
    return False

Loading State

from dash import dcc

app.layout = dmc.MantineProvider([
    dmc.Button("Load Data", id="load-btn"),
    dcc.Loading(
        id="loading",
        type="circle",
        children=dmc.Container(id="data-container"),
    ),
])

@callback(Output("data-container", "children"), Input("load-btn", "n_clicks"))
def load_data(n):
    import time
    time.sleep(2)  # Simulate slow operation
    return dmc.Text("Data loaded!")

Chart with Data

data = [
    {"month": "Jan", "sales": 100, "profit": 20},
    {"month": "Feb", "sales": 150, "profit": 35},
    {"month": "Mar", "sales": 120, "profit": 25},
]

dmc.BarChart(
    data=data,
    dataKey="month",
    series=[
        {"name": "sales", "color": "blue.6"},
        {"name": "profit", "color": "green.6"},
    ],
    h=300,
    withLegend=True,
    withTooltip=True,
)

---

Troubleshooting

Common Errors

Debug Tips

1. Check browser console for JavaScript errors 2. Use `debug=True` in app.run() for detailed Python errors 3. Print `ctx.triggered_id` to see which input fired 4. Validate JSON-serializable callback returns (no Python objects) 5. Test with `prevent_initial_call=True` to avoid startup errors

DMC v2.x Gotchas

• DateTimePicker: Use timePickerProps not timeInputProps
• Carousel: Embla options need {"containScroll": "trimSnaps"} wrapper
• Default reuseTargetNode=True may cause Portal issues - set to False if overlays misbehave
• Use MantineProvider not MantineProviderV2 (deprecated)

→ Full migration guide: references/migration-v2.md

Dash Advanced Callbacks Reference

Comprehensive guide to advanced callback patterns including standard callbacks, pattern-matching, callback context, clientside callbacks, background callbacks, and DMC-specific features.

Table of Contents

1. Standard Callbacks: Input/Output/State 2. Pattern-Matching Callbacks 3. Callback Context (ctx) 4. Clientside Callbacks 5. Background Callbacks 6. PreventUpdate and no_update 7. Running Parameter 8. Allow Duplicate 9. DMC-Specific Features

---

Standard Callbacks: Input/Output/State

Basic Callback Structure

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

@callback(
    Output('output-id', 'property-name'),
    Input('input-id', 'property-name'),
    State('state-id', 'property-name')
)
def callback_function(input_value, state_value):
    """
    Inputs: Trigger callback when property changes
    State: Provide current value but don't trigger
    Output: Update this component property
    """
    return f"Input: {input_value}, State: {state_value}"

Multiple Inputs and Outputs

@callback(
    Output('output-1', 'children'),
    Output('output-2', 'children'),
    Output('output-3', 'style'),
    Input('dropdown-1', 'value'),
    Input('dropdown-2', 'value'),
    Input('slider', 'value'),
    State('text-input', 'value')
)
def multi_callback(dd1_val, dd2_val, slider_val, text_val):
    """Multiple inputs/outputs - order matches function arguments."""
    return (
        f"Dropdown 1: {dd1_val}",
        f"Dropdown 2: {dd2_val}",
        {'color': 'red' if slider_val > 50 else 'blue'}
    )

Flexible Callback Signatures (Dash 2.0+)

Use dictionaries for keyword arguments - order doesn't matter:

@callback(
    output=dict(
        title=Output('title', 'children'),
        figure=Output('graph', 'figure')
    ),
    inputs=dict(
        category=Input('category-dropdown', 'value'),
        year=Input('year-slider', 'value')
    ),
    state=dict(
        data=State('data-store', 'data')
    )
)
def update_dashboard(category, year, data):
    """Named arguments - order-independent."""
    df = pd.DataFrame(data)
    filtered = df[(df['cat'] == category) & (df['year'] == year)]

    return dict(
        title=f"{category} in {year}",
        figure=px.bar(filtered, x='x', y='y')
    )

Chained Callbacks

Output of one callback becomes input to another:

@callback(
    Output('intermediate-data', 'data'),
    Input('upload-data', 'contents')
)
def process_upload(contents):
    """First callback: Process uploaded file."""
    df = parse_contents(contents)
    return df.to_dict('records')

@callback(
    Output('graph', 'figure'),
    Input('intermediate-data', 'data'),
    Input('chart-type', 'value')
)
def update_graph(data, chart_type):
    """Second callback: Create visualization from processed data."""
    df = pd.DataFrame(data)
    if chart_type == 'bar':
        return px.bar(df, x='x', y='y')
    return px.line(df, x='x', y='y')

---

Pattern-Matching Callbacks

Pattern-matching allows callbacks to respond to dynamic numbers of components using ALL, MATCH, and ALLSMALLER selectors.

Component IDs as Dictionaries

# Static ID (traditional)
html.Button("Click", id="my-button")

# Dynamic ID (pattern-matching)
html.Button("Click", id={"type": "filter-btn", "index": 0})
html.Button("Click", id={"type": "filter-btn", "index": 1})

ALL Selector

Matches all components with specified type - passes all values as a list.

from dash import ALL, Patch

app.layout = html.Div([
    html.Button("Add Filter", id="add-filter-btn", n_clicks=0),
    html.Div(id="dropdown-container", children=[]),
    html.Div(id="output")
])

@callback(
    Output("dropdown-container", "children"),
    Input("add-filter-btn", "n_clicks")
)
def add_dropdown(n_clicks):
    """Dynamically add dropdowns using Patch."""
    patched_children = Patch()
    new_dropdown = dcc.Dropdown(
        options=['NYC', 'MTL', 'LA', 'TOKYO'],
        id={"type": "city-dropdown", "index": n_clicks}
    )
    patched_children.append(new_dropdown)
    return patched_children

@callback(
    Output("output", "children"),
    Input({"type": "city-dropdown", "index": ALL}, "value")
)
def display_output(values):
    """
    Triggered when ANY dropdown changes.
    Receives ALL dropdown values as a list.
    """
    return html.Div([
        html.Div(f"Dropdown {i + 1} = {val}")
        for i, val in enumerate(values)
        if val is not None
    ])

MATCH Selector

Matches individual components - creates separate callback instance per matched component.

app.layout = html.Div([
    html.Button("Add Item", id="add-btn", n_clicks=0),
    html.Div(id="container", children=[])
])

@callback(
    Output("container", "children"),
    Input("add-btn", "n_clicks")
)
def add_item(n_clicks):
    """Add dropdown and corresponding output div."""
    patched_children = Patch()

    new_elements = html.Div([
        dcc.Dropdown(
            ['Option A', 'Option B', 'Option C'],
            id={"type": "dynamic-dropdown", "index": n_clicks}
        ),
        html.Div(id={"type": "dynamic-output", "index": n_clicks})
    ])

    patched_children.append(new_elements)
    return patched_children

@callback(
    Output({"type": "dynamic-output", "index": MATCH}, "children"),
    Input({"type": "dynamic-dropdown", "index": MATCH}, "value"),
    State({"type": "dynamic-dropdown", "index": MATCH}, "id")
)
def update_output(value, component_id):
    """
    Separate callback instance for EACH dropdown.
    Only receives the value from the MATCHING dropdown.
    """
    return f"Dropdown {component_id['index']} selected: {value}"

ALLSMALLER Selector

Passes values from components with smaller indices - useful for cascading filters.

app.layout = html.Div([
    html.Button("Add Filter", id="add-filter", n_clicks=0),
    html.Div(id="filter-container", children=[])
])

@callback(
    Output("filter-container", "children"),
    Input("add-filter", "n_clicks")
)
def add_filter_level(n_clicks):
    """Add cascading filter dropdowns."""
    patched_children = Patch()

    filter_div = html.Div([
        html.Label(f"Filter Level {n_clicks}"),
        dcc.Dropdown(id={"type": "filter-dd", "index": n_clicks}),
        html.Div(id={"type": "filter-output", "index": n_clicks})
    ])

    patched_children.append(filter_div)
    return patched_children

@callback(
    Output({"type": "filter-output", "index": MATCH}, "children"),
    Input({"type": "filter-dd", "index": MATCH}, "value"),
    Input({"type": "filter-dd", "index": ALLSMALLER}, "value")
)
def update_cascading_filter(current_value, previous_values):
    """
    Receives:
    - current_value: Value from MATCHING dropdown
    - previous_values: List of values from ALL dropdowns with smaller indices
    """
    if current_value is None:
        return "Select a value"

    # All filter values in order (oldest to newest)
    all_filter_values = previous_values[::-1] + [current_value]

    # Apply progressive filtering
    filtered_count = apply_filters(all_filter_values)

    return f"Filters applied: {all_filter_values} → {filtered_count} results"

Pattern-Matching with Multiple Types

app.layout = html.Div([
    html.Button("Add Chart", id="add-chart", n_clicks=0),
    html.Div(id="charts-container", children=[])
])

@callback(
    Output("charts-container", "children"),
    Input("add-chart", "n_clicks")
)
def add_chart_controls(n_clicks):
    """Add chart with multiple control types."""
    patched_children = Patch()

    chart_group = html.Div([
        dcc.Dropdown(
            ['bar', 'line', 'scatter'],
            'bar',
            id={"type": "chart-type", "index": n_clicks}
        ),
        dcc.Slider(
            min=0, max=100, value=50,
            id={"type": "chart-slider", "index": n_clicks}
        ),
        dcc.Graph(id={"type": "chart-graph", "index": n_clicks})
    ])

    patched_children.append(chart_group)
    return patched_children

@callback(
    Output({"type": "chart-graph", "index": MATCH}, "figure"),
    Input({"type": "chart-type", "index": MATCH}, "value"),
    Input({"type": "chart-slider", "index": MATCH}, "value")
)
def update_chart(chart_type, slider_value):
    """Each chart responds to its own controls."""
    df = generate_data(slider_value)

    if chart_type == 'bar':
        return px.bar(df, x='x', y='y')
    elif chart_type == 'line':
        return px.line(df, x='x', y='y')
    return px.scatter(df, x='x', y='y')

---

Callback Context (ctx)

Access information about which component triggered the callback using dash.callback_context.

Basic ctx Usage

from dash import ctx
import json

@callback(
    Output('output', 'children'),
    Input('btn-1', 'n_clicks'),
    Input('btn-2', 'n_clicks'),
    Input('btn-3', 'n_clicks')
)
def display_clicked_button(btn1, btn2, btn3):
    """Determine which button was clicked."""
    if not ctx.triggered:
        return "No button clicked yet"

    # Get ID of triggering component
    button_id = ctx.triggered_id

    return f"Button '{button_id}' was clicked"

ctx Properties

@callback(
    Output('debug-output', 'children'),
    Input('input-1', 'value'),
    Input('input-2', 'value'),
    State('state-1', 'value')
)
def debug_callback(input1, input2, state1):
    """Explore all ctx properties."""
    info = {
        'triggered_id': ctx.triggered_id,  # ID of component that triggered
        'triggered': ctx.triggered,  # List of triggered inputs
        'triggered_prop_ids': ctx.triggered_prop_ids,  # Dict mapping IDs to props
        'inputs': ctx.inputs,  # All input values by ID
        'states': ctx.states,  # All state values by ID
        'outputs_list': ctx.outputs_list  # List of outputs
    }

    return html.Pre(json.dumps(info, indent=2))

ctx with Pattern-Matching

@callback(
    Output('selected-info', 'children'),
    Input({'type': 'item-btn', 'index': ALL}, 'n_clicks')
)
def handle_dynamic_clicks(n_clicks_list):
    """Determine which dynamic button was clicked."""
    if not ctx.triggered_id:
        return "Click a button"

    # ctx.triggered_id is the dictionary ID
    clicked_id = ctx.triggered_id
    clicked_index = clicked_id['index']

    return f"Button at index {clicked_index} was clicked"

ctx.args_grouping

Access grouped arguments when using flexible callback signatures:

@callback(
    output=dict(
        output1=Output('out-1', 'children'),
        output2=Output('out-2', 'children')
    ),
    inputs=dict(
        input1=Input('in-1', 'value'),
        input2=Input('in-2', 'value')
    )
)
def grouped_callback(**kwargs):
    """Access inputs through ctx.args_grouping."""
    inputs = ctx.args_grouping['inputs']

    return dict(
        output1=f"Input 1: {inputs['input1']['value']}",
        output2=f"Input 2: {inputs['input2']['value']}"
    )

Conditional Logic Based on Trigger

@callback(
    Output('display', 'children'),
    Input('submit-btn', 'n_clicks'),
    Input('reset-btn', 'n_clicks'),
    State('input-field', 'value')
)
def handle_buttons(submit_clicks, reset_clicks, input_value):
    """Different actions based on which button triggered."""
    if not ctx.triggered_id:
        raise PreventUpdate

    if ctx.triggered_id == 'submit-btn':
        return f"Submitted: {input_value}"
    elif ctx.triggered_id == 'reset-btn':
        return "Form reset"

    return "Unknown action"

---

Clientside Callbacks

Execute callbacks in JavaScript directly in the browser for better performance with frequent updates or large data transfers.

Inline JavaScript

from dash import clientside_callback, Input, Output

clientside_callback(
    """
    function(n_clicks) {
        return 'Clicked ' + n_clicks + ' times';
    }
    """,
    Output('output', 'children'),
    Input('button', 'n_clicks')
)

External JavaScript Files

Create assets/custom_clientside.js:

window.dash_clientside = Object.assign({}, window.dash_clientside, {
    clientside: {
        update_chart: function(slider_value, dropdown_value) {
            // Complex JavaScript logic
            const data = processData(slider_value, dropdown_value);
            return {
                data: data,
                layout: {title: 'Updated Chart'}
            };
        },

        format_number: function(value) {
            return new Intl.NumberFormat('en-US', {
                style: 'currency',
                currency: 'USD'
            }).format(value);
        }
    }
});

Reference in Python:

from dash import ClientsideFunction

clientside_callback(
    ClientsideFunction(
        namespace='clientside',
        function_name='update_chart'
    ),
    Output('graph', 'figure'),
    Input('slider', 'value'),
    Input('dropdown', 'value')
)

Async Clientside Callbacks (Dash 2.4+)

Use promises for asynchronous operations:

clientside_callback(
    """
    async function(url) {
        try {
            const response = await fetch(url);
            const data = await response.json();
            return data;
        } catch (error) {
            console.error('Fetch error:', error);
            return dash_clientside.no_update;
        }
    }
    """,
    Output('data-table', 'data'),
    Input('api-endpoint', 'value')
)

Clientside Callback Context

clientside_callback(
    """
    function(btn1_clicks, btn2_clicks) {
        const triggered_id = dash_clientside.callback_context.triggered_id;

        if (triggered_id === 'btn-1') {
            return 'Button 1 clicked';
        } else if (triggered_id === 'btn-2') {
            return 'Button 2 clicked';
        }

        return 'No button clicked';
    }
    """,
    Output('output', 'children'),
    Input('btn-1', 'n_clicks'),
    Input('btn-2', 'n_clicks')
)

Partial Updates with Patch (Dash 3.3+)

clientside_callback(
    """
    function(n_clicks) {
        var patch = new dash_clientside.Patch();

        // Toggle legend visibility
        var showLegend = (n_clicks % 2 === 0);

        // Only update specific property path
        patch.assign(['layout', 'showlegend'], showLegend);

        return patch.build();
    }
    """,
    Output('graph', 'figure'),
    Input('toggle-legend-btn', 'n_clicks')
)

Set Props for Direct Updates (Dash 2.16+)

app.clientside_callback(
    """
    function() {
        // Listen for keyboard shortcuts
        document.addEventListener('keydown', function(e) {
            // Ctrl+S to save
            if (e.ctrlKey && e.keyCode == 83) {
                e.preventDefault();
                dash_clientside.set_props('save-indicator', {
                    children: 'Saving...',
                    style: {color: 'orange'}
                });

                // Simulate save
                setTimeout(function() {
                    dash_clientside.set_props('save-indicator', {
                        children: 'Saved!',
                        style: {color: 'green'}
                    });
                }, 1000);
            }
        });

        return dash_clientside.no_update;
    }
    """,
    Output('init-trigger', 'data'),
    Input('init-trigger', 'data')
)

PreventUpdate and no_update in Clientside

clientside_callback(
    """
    function(value) {
        if (value === null || value === undefined) {
            throw new window.dash_clientside.PreventUpdate();
        }

        if (value < 0) {
            return dash_clientside.no_update;
        }

        return 'Value: ' + value;
    }
    """,
    Output('output', 'children'),
    Input('input', 'value')
)

---

Background Callbacks

Execute long-running callbacks in separate worker processes to avoid timeouts and blocking.

Setup with DiskcacheManager

For local development:

from dash import Dash, DiskcacheManager, CeleryManager, Input, Output, callback
import diskcache

# Create cache directory
cache = diskcache.Cache("./cache")
background_callback_manager = DiskcacheManager(cache)

app = Dash(__name__, background_callback_manager=background_callback_manager)

Setup with CeleryManager

For production with Redis:

import os
from celery import Celery

# Configure Celery
celery_app = Celery(
    __name__,
    broker=os.environ.get('REDIS_URL', 'redis://localhost:6379/0'),
    backend=os.environ.get('REDIS_URL', 'redis://localhost:6379/1')
)

background_callback_manager = CeleryManager(
    celery_app,
    cache_by=[lambda: session_id]  # Isolate by session
)

app = Dash(__name__, background_callback_manager=background_callback_manager)

Basic Background Callback

@callback(
    Output('result', 'children'),
    Input('submit-btn', 'n_clicks'),
    State('input-data', 'value'),
    background=True,
    manager=background_callback_manager
)
def long_running_process(n_clicks, data):
    """Runs in background worker process."""
    if not n_clicks:
        raise PreventUpdate

    # Simulate long operation
    time.sleep(10)
    result = expensive_computation(data)

    return f"Processing complete: {result}"

Progress Tracking

app.layout = html.Div([
    html.Button('Start', id='start-btn'),
    dmc.Progress(id='progress-bar', value=0),
    html.Div(id='progress-text'),
    html.Div(id='result')
])

@callback(
    output=Output('result', 'children'),
    inputs=Input('start-btn', 'n_clicks'),
    background=True,
    manager=background_callback_manager,
    progress=[
        Output('progress-bar', 'value'),
        Output('progress-text', 'children')
    ],
    prevent_initial_call=True
)
def process_with_progress(set_progress, n_clicks):
    """
    Background callback with progress updates.

    set_progress is automatically injected as first parameter.
    """
    total_steps = 10

    for i in range(total_steps):
        # Simulate work
        time.sleep(1)

        # Update progress
        progress_value = int((i + 1) / total_steps * 100)
        set_progress((progress_value, f'Step {i + 1}/{total_steps}'))

    return "Processing complete!"

Cancellation Support

app.layout = html.Div([
    html.Button('Start Processing', id='start-btn'),
    html.Button('Cancel', id='cancel-btn'),
    html.Div(id='status'),
    dmc.Progress(id='progress', value=0)
])

@callback(
    output=Output('status', 'children'),
    inputs=Input('start-btn', 'n_clicks'),
    background=True,
    manager=background_callback_manager,
    running=[
        (Output('start-btn', 'disabled'), True, False),
        (Output('cancel-btn', 'disabled'), False, True)
    ],
    cancel=Input('cancel-btn', 'n_clicks'),
    progress=Output('progress', 'value')
)
def cancellable_process(set_progress, n_clicks):
    """
    Background callback that can be cancelled.

    When cancel input triggers, callback is terminated.
    """
    for i in range(100):
        time.sleep(0.5)
        set_progress(i + 1)

    return "Processing complete!"

set_props for Dynamic Updates (Dash 2.17+)

from dash import set_props

@callback(
    Output('final-output', 'children'),
    Input('stream-btn', 'n_clicks'),
    background=True,
    manager=background_callback_manager
)
def streaming_updates(set_progress, n_clicks):
    """
    Use set_props to update components not in callback outputs.
    """
    if not n_clicks:
        raise PreventUpdate

    # Update multiple components dynamically
    for i in range(10):
        time.sleep(1)

        # Update any component property on the page
        set_props('live-status', {'children': f'Processing step {i + 1}'})
        set_props('live-chart', {'figure': generate_chart(i)})

        # Also update progress output
        set_progress(f'Step {i + 1}/10')

    return "Streaming complete!"

Running State Management

@callback(
    Output('result', 'children'),
    Input('submit-btn', 'n_clicks'),
    background=True,
    manager=background_callback_manager,
    running=[
        (Output('submit-btn', 'disabled'), True, False),
        (Output('submit-btn', 'children'), 'Processing...', 'Submit'),
        (Output('loading-spinner', 'style'), {'display': 'block'}, {'display': 'none'})
    ]
)
def process_with_running_state(n_clicks):
    """
    running parameter: (Output, value_while_running, value_after_completion)
    """
    time.sleep(5)
    return "Processing complete"

---

PreventUpdate and no_update

PreventUpdate: Block All Updates

from dash.exceptions import PreventUpdate

@callback(
    Output('output-1', 'children'),
    Output('output-2', 'children'),
    Input('input', 'value')
)
def conditional_update(value):
    """Prevent all outputs from updating."""
    if value is None or value == '':
        # Stop callback execution entirely
        raise PreventUpdate

    return f"Value: {value}", f"Length: {len(value)}"

no_update: Selective Updates

from dash import no_update

@callback(
    Output('valid-output', 'children'),
    Output('error-output', 'children'),
    Output('warning-output', 'children'),
    Input('input', 'value')
)
def selective_update(value):
    """Update only specific outputs."""
    if value is None:
        raise PreventUpdate

    # Validation
    if len(value) < 3:
        # Only update error, leave others unchanged
        return no_update, "Must be at least 3 characters", no_update

    if any(char.isdigit() for char in value):
        # Only update warning
        return no_update, no_update, "Contains numbers"

    # Valid input - update valid output, clear error/warning
    return f"Valid: {value}", "", ""

Combining PreventUpdate and no_update

@callback(
    Output('data-display', 'children'),
    Output('error-msg', 'children'),
    Input('fetch-btn', 'n_clicks'),
    State('api-url', 'value')
)
def fetch_data(n_clicks, url):
    """Prevent vs selective update based on conditions."""
    # Prevent update on initial load
    if not n_clicks:
        raise PreventUpdate

    # Validate URL
    if not url:
        # Update only error message
        return no_update, "Please enter a URL"

    try:
        data = requests.get(url).json()
        # Clear error, update data
        return json.dumps(data, indent=2), ""
    except Exception as e:
        # Update only error, leave data unchanged
        return no_update, f"Error: {str(e)}"

---

Running Parameter

Show loading states and disable controls during callback execution.

Basic Usage

@callback(
    Output('result', 'children'),
    Input('submit-btn', 'n_clicks'),
    running=[
        (Output('submit-btn', 'disabled'), True, False)
    ]
)
def process_data(n_clicks):
    """Button disabled while callback runs."""
    if not n_clicks:
        raise PreventUpdate

    time.sleep(3)  # Simulate work
    return "Complete!"

Multiple Running States

@callback(
    Output('output', 'children'),
    Input('process-btn', 'n_clicks'),
    running=[
        (Output('process-btn', 'disabled'), True, False),
        (Output('process-btn', 'children'), 'Processing...', 'Process'),
        (Output('loading-overlay', 'style'), {'display': 'flex'}, {'display': 'none'}),
        (Output('cancel-btn', 'disabled'), False, True)
    ]
)
def long_process(n_clicks):
    """Multiple UI updates during execution."""
    if not n_clicks:
        raise PreventUpdate

    time.sleep(5)
    return "Processing complete!"

With DMC Components

import dash_mantine_components as dmc

@callback(
    Output('result', 'children'),
    Input('submit-btn', 'n_clicks'),
    running=[
        (Output('submit-btn', 'loading'), True, False),
        (Output('submit-btn', 'disabled'), True, False),
        (Output('progress-bar', 'style'), {'display': 'block'}, {'display': 'none'})
    ]
)
def process_with_dmc(n_clicks):
    """DMC Button has built-in loading prop."""
    if not n_clicks:
        raise PreventUpdate

    time.sleep(3)
    return "Done!"

---

Allow Duplicate

Allow multiple callbacks to update the same output property.

Basic allow_duplicate Usage

# First callback updates output
@callback(
    Output('display', 'children'),
    Input('btn-1', 'n_clicks')
)
def update_from_btn1(n_clicks):
    """Primary callback - no allow_duplicate needed."""
    return f"Button 1 clicked {n_clicks} times"

# Second callback also updates same output
@callback(
    Output('display', 'children', allow_duplicate=True),
    Input('btn-2', 'n_clicks'),
    prevent_initial_call=True  # Required with allow_duplicate
)
def update_from_btn2(n_clicks):
    """Secondary callback - requires allow_duplicate."""
    return f"Button 2 clicked {n_clicks} times"

Reset Pattern

@callback(
    Output('counter', 'children'),
    Input('increment-btn', 'n_clicks'),
    State('counter', 'children')
)
def increment(n_clicks, current):
    """Main counter logic."""
    if current is None:
        current = "0"
    return str(int(current) + 1)

@callback(
    Output('counter', 'children', allow_duplicate=True),
    Input('reset-btn', 'n_clicks'),
    prevent_initial_call=True
)
def reset_counter(n_clicks):
    """Reset counter to zero."""
    return "0"

Validation + Update Pattern

@callback(
    Output('validated-input', 'value'),
    Output('error-msg', 'children'),
    Input('validated-input', 'value')
)
def validate_input(value):
    """Primary validation callback."""
    if value and not value.isalnum():
        return value, "Only alphanumeric characters allowed"
    return value, ""

@callback(
    Output('validated-input', 'value', allow_duplicate=True),
    Input('clear-btn', 'n_clicks'),
    prevent_initial_call=True
)
def clear_input(n_clicks):
    """Clear input on button click."""
    return ""

---

DMC-Specific Features

Debounce Property

DMC components support debounce prop to limit callback firing frequency:

import dash_mantine_components as dmc

app.layout = dmc.MantineProvider([
    dmc.TextInput(
        id='search-input',
        label='Search',
        placeholder='Type to search...',
        debounce=500  # Wait 500ms after typing stops
    ),
    html.Div(id='search-results')
])

@callback(
    Output('search-results', 'children'),
    Input('search-input', 'value')
)
def search(query):
    """Only fires 500ms after user stops typing."""
    if not query:
        return ""

    results = perform_search(query)
    return f"Found {len(results)} results for '{query}'"

Persistence Properties

DMC components support persistence for storing user input across sessions:

dmc.TextInput(
    id='username-input',
    persistence=True,  # Enable persistence
    persistence_type='local'  # 'local', 'session', or 'memory'
)

dmc.MultiSelect(
    id='tags-select',
    data=['Python', 'JavaScript', 'Rust', 'Go'],
    persistence=True,
    persistence_type='session'
)

Loading Overlays

import dash_mantine_components as dmc

app.layout = dmc.MantineProvider([
    dmc.Button('Load Data', id='load-btn'),
    dmc.LoadingOverlay(
        dmc.Table(id='data-table'),
        id='table-loader'
    )
])

@callback(
    Output('data-table', 'children'),
    Output('table-loader', 'visible'),
    Input('load-btn', 'n_clicks'),
    running=[
        (Output('table-loader', 'visible'), True, False)
    ]
)
def load_data(n_clicks):
    """Show loading overlay during data fetch."""
    if not n_clicks:
        raise PreventUpdate

    time.sleep(2)  # Simulate data loading
    data = fetch_data()

    return create_table(data), False

Notifications

import dash_mantine_components as dmc

@callback(
    Output('notification-container', 'children'),
    Input('submit-btn', 'n_clicks'),
    State('form-data', 'value'),
    prevent_initial_call=True
)
def show_notification(n_clicks, data):
    """Display notification based on validation."""
    if not data:
        return dmc.Notification(
            title="Validation Error",
            message="Please fill in all required fields",
            color="red",
            action="show",
            id="error-notification"
        )

    # Process data
    success = process_form(data)

    if success:
        return dmc.Notification(
            title="Success",
            message="Form submitted successfully!",
            color="green",
            action="show",
            icon=DashIconify(icon="mdi:check-circle"),
            id="success-notification"
        )

    return dmc.Notification(
        title="Error",
        message="An error occurred during submission",
        color="red",
        action="show",
        id="error-notification"
    )

Modals with Callbacks

app.layout = dmc.MantineProvider([
    dmc.Button('Open Modal', id='open-modal-btn'),
    dmc.Modal(
        title='Confirm Action',
        id='confirm-modal',
        children=[
            dmc.Text('Are you sure you want to proceed?'),
            dmc.Group([
                dmc.Button('Cancel', id='cancel-btn', variant='outline'),
                dmc.Button('Confirm', id='confirm-btn', color='red')
            ])
        ]
    ),
    html.Div(id='action-result')
])

@callback(
    Output('confirm-modal', 'opened'),
    Input('open-modal-btn', 'n_clicks'),
    Input('cancel-btn', 'n_clicks'),
    Input('confirm-btn', 'n_clicks'),
    State('confirm-modal', 'opened'),
    prevent_initial_call=True
)
def toggle_modal(open_clicks, cancel_clicks, confirm_clicks, is_open):
    """Toggle modal visibility based on button clicks."""
    if ctx.triggered_id == 'open-modal-btn':
        return True
    elif ctx.triggered_id in ['cancel-btn', 'confirm-btn']:
        return False
    return is_open

@callback(
    Output('action-result', 'children'),
    Input('confirm-btn', 'n_clicks'),
    prevent_initial_call=True
)
def perform_action(n_clicks):
    """Execute action when confirmed."""
    perform_critical_operation()
    return "Action completed successfully"

---

References

Based on official Dash documentation:

• Advanced Callbacks
• Pattern-Matching Callbacks
• Clientside Callbacks
• Background Callbacks
• Flexible Callback Signatures
• Dash Mantine Components

DMC Charts Data Formats and Configuration

Complete reference for data formats, series configuration, and common properties across all DMC chart components.

Table of Contents

• Data Format
• Series Configuration
• Common Chart Props
• Chart Types
• Axis Configuration
• Styling and Customization

Data Format

General Structure

All DMC charts accept data as a list of dictionaries:

data = [
    {"date": "Mar 22", "Apples": 2890, "Oranges": 2338, "Tomatoes": 2452},
    {"date": "Mar 23", "Apples": 2756, "Oranges": 2103, "Tomatoes": 2402},
    {"date": "Mar 24", "Apples": 3322, "Oranges": 986, "Tomatoes": 1821},
]

Key Requirements:

• Each dictionary represents one data point
• Must have a dataKey field (e.g., "date", "month", "category")
• Additional fields correspond to series names

Chart-Specific Data

AreaChart, LineChart, BarChart:

data = [
    {"month": "January", "Smartphones": 1200, "Laptops": 900, "Tablets": 200},
    {"month": "February", "Smartphones": 1900, "Laptops": 1200, "Tablets": 400},
]

Waterfall Chart (BarChart type="waterfall"):

data = [
    {"item": "TaxRate", "value": 21, "color": "blue"},
    {"item": "Foreign inc.", "value": -15.5, "color": "teal"},
    {"item": "ETR", "value": 3.5, "color": "blue", "standalone": True},
]

Split Area Chart (type="split"):

data = [
    {"date": "Mar 22", "value": 110},
    {"date": "Mar 23", "value": 60},
    {"date": "Mar 24", "value": -80},  # Negative values
]

Series Configuration

Basic Series Structure

series = [
    {"name": "Apples", "color": "indigo.6"},
    {"name": "Oranges", "color": "blue.6"},
    {"name": "Tomatoes", "color": "teal.6"}
]

Series Properties

Required:

• name (string) - Must match a key in the data

Optional:

• color (string) - Theme color reference (e.g., "blue.6") or CSS color
• label (string) - Display label in legend (defaults to name)
• yAxisId (string) - Bind to right Y axis: "right"
• strokeDasharray (string) - Line style: "5 5" for dashed
• fill (string) - Bar fill pattern: "url(#pattern-id)"
• stackId (string) - Group series in stacked charts

Examples

Custom Labels:

series = [
    {"name": "Apples", "label": "Apple Sales", "color": "red.6"},
    {"name": "Oranges", "label": "Orange Sales", "color": "orange.6"},
]

Right Y Axis:

series = [
    {"name": "temperature", "color": "red.6"},
    {"name": "humidity", "color": "blue.6", "yAxisId": "right"},
]

Dashed Lines:

series = [
    {"name": "Actual", "color": "blue.6"},
    {"name": "Forecast", "color": "gray.6", "strokeDasharray": "5 5"},
]

Common Chart Props

Data Props

• data (list[dict], required) - Chart data
• dataKey (str, required) - Key for X-axis values
• series (list[dict], required) - Series configuration

Display Props

• h (int) - Chart height in pixels
• withLegend (bool) - Show legend (default: False)
• withTooltip (bool) - Show tooltip (default: True)
• withXAxis (bool) - Show X axis (default: True)
• withYAxis (bool) - Show Y axis (default: True)
• withDots (bool) - Show data point dots (default: True for Line/Area)

Axis Props

• xAxisLabel (str) - Label below X axis
• yAxisLabel (str) - Label next to Y axis
• xAxisProps (dict) - Props for recharts XAxis
• yAxisProps (dict) - Props for recharts YAxis
• withRightYAxis (bool) - Show right Y axis
• rightYAxisLabel (str) - Label for right Y axis
• rightYAxisProps (dict) - Props for right YAxis

Grid and Styling

• gridAxis (str) - Grid lines: "none", "x", "y", "xy" (default: "x")
• tickLine (str) - Tick lines: "none", "x", "y", "xy" (default: "y")
• gridColor (str) - Grid line color
• textColor (str) - Text color
• strokeDasharray (str) - Grid dash pattern (default: "5 5")

Tooltip and Animation

• tooltipAnimationDuration (int) - Tooltip animation in ms (default: 0)
• tooltipProps (dict) - Props for recharts Tooltip
• valueFormatter (dict) - Function to format values: {"function": "funcName"}

Legend

• legendProps (dict) - Props for recharts Legend
• verticalAlign: "top"/"middle"/"bottom"
• height: Number in pixels
• align: "left"/"center"/"right"

Chart Types

AreaChart

Types:

• type="default" - Regular area chart
• type="stacked" - Stacked areas
• type="percent" - Percentage stacked
• type="split" - Split by positive/negative

Specific Props:

• withGradient (bool) - Gradient fill (default: False)
• splitColors (list) - Colors for split type: ["green.7", "red.7"]
• curveType (str) - Line curve: "monotone", "linear", "natural", "step"
• fillOpacity (float) - Area opacity: 0-1 (default: 0.2)
• strokeWidth (int) - Line width (default: 2)
• connectNulls (bool) - Connect across null values (default: True)
• dotProps (dict) - Props for dots
• activeDotProps (dict) - Props for active dot

BarChart

Types:

• type="default" - Regular bars
• type="stacked" - Stacked bars
• type="percent" - Percentage stacked
• type="waterfall" - Waterfall chart

Specific Props:

• orientation (str) - "horizontal" or "vertical"
• withBarValueLabel (bool) - Show values on bars
• valueLabelProps (dict) - Props for value labels
• barProps (dict) - Props for recharts Bar
• getBarColor (dict) - Function to color bars: {"function": "funcName"}
• fillOpacity (float) - Bar opacity (default: 1)
• maxBarWidth (int) - Max bar width in pixels
• minBarSize (int) - Min bar height in pixels
• cursorFill (str) - Hover fill color

LineChart

Types:

• type="default" - Regular line chart
• type="gradient" - Gradient fill

Specific Props:

• curveType (str) - Line curve: "monotone", "linear", "natural", "step"
• strokeWidth (int) - Line width (default: 2)
• connectNulls (bool) - Connect across nulls (default: True)
• dotProps (dict) - Props for dots
• activeDotProps (dict) - Props for active dot
• gradientStops (list) - Gradient colors for gradient type:

  [
      {"offset": 0, "color": "red.6"},
      {"offset": 50, "color": "yellow.5"},
      {"offset": 100, "color": "blue.5"}
  ]

Axis Configuration

X Axis

xAxisProps = {
    "angle": -20,                          # Rotate labels
    "tickMargin": 15,                      # Space between tick and label
    "orientation": "top",                  # "top" or "bottom"
    "padding": {"left": 30, "right": 30}, # End padding
}

Y Axis

yAxisProps = {
    "domain": [0, 100],                    # Fixed range
    "tickMargin": 15,                      # Space between tick and label
    "orientation": "right",                # "left" or "right"
}

Dual Y Axis

dmc.AreaChart(
    data=data,
    dataKey="name",
    withRightYAxis=True,
    yAxisLabel="Primary",
    rightYAxisLabel="Secondary",
    series=[
        {"name": "primary", "color": "blue.6"},
        {"name": "secondary", "color": "red.6", "yAxisId": "right"},
    ],
)

Styling and Customization

Colors

Theme Colors:

series = [
    {"name": "series1", "color": "blue.6"},      # Theme color
    {"name": "series2", "color": "orange.7"},
    {"name": "series3", "color": "#FF5733"},     # CSS color
]

Color Scheme Dependent:

# In CSS file:
"""
:root {
  --chart-color: var(--mantine-color-orange-8)
}

:root[data-mantine-color-scheme="dark"] {
  --chart-color: var(--mantine-color-lime-4);
}
"""

# In Python:
series = [{"name": "data", "color": "var(--chart-color)"}]

Grid and Text Colors

Using CSS Variables:

# In CSS:
"""
.custom-chart {
  --chart-grid-color: var(--mantine-color-blue-5);
  --chart-text-color: var(--mantine-color-blue-8);
}
"""

# In Python:
dmc.BarChart(className="custom-chart", ...)

Using Props (single color scheme):

dmc.LineChart(
    gridColor="gray.5",
    textColor="gray.9",
    ...
)

Reference Lines

referenceLines = [
    {
        "y": 50,
        "label": "Target",
        "color": "red.6",
        "labelPosition": "insideTopRight"
    },
    {
        "x": "Mar 25",
        "label": "Event",
        "color": "blue.6"
    }
]

Units

dmc.BarChart(
    data=data,
    unit="$",        # Adds $ to Y-axis ticks and tooltip
    ...
)

Value Formatting

Use custom JavaScript functions for formatting:

# In Python:
dmc.AreaChart(
    valueFormatter={"function": "formatCurrency"},
    ...
)

// In assets/custom.js:
var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {};

dmcfuncs.formatCurrency = (value) => {
    return new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: 'USD'
    }).format(value);
};

Sync Multiple Charts

Sync tooltips across charts with same syncId:

dmc.Stack([
    dmc.AreaChart(
        areaChartProps={"syncId": "sales"},
        ...
    ),
    dmc.BarChart(
        barChartProps={"syncId": "sales"},
        ...
    ),
])

Interactive Features

Click and Hover Data

from dash import callback, Input, Output

dmc.BarChart(id="chart", ...)

@callback(
    Output("output", "children"),
    Input("chart", "clickData"),
    Input("chart", "clickSeriesName"),
)
def handle_click(data, series_name):
    return f"Clicked: {data}, Series: {series_name}"

@callback(
    Output("hover-output", "children"),
    Input("chart", "hoverData"),
    Input("chart", "hoverSeriesName"),
)
def handle_hover(data, series_name):
    return f"Hovering: {data}, Series: {series_name}"

Highlight on Hover

dmc.LineChart(
    highlightHover=True,  # Highlight series on hover
    ...
)

Best Practices

1. Consistent data keys - Use the same field names across all data points 2. Handle nulls - Set connectNulls based on desired behavior 3. Color accessibility - Use high contrast colors for better readability 4. Responsive heights - Use appropriate h values for different screen sizes 5. Format values - Use valueFormatter for consistent number formatting 6. Limit series - Too many series can make charts hard to read 7. Use legends - Enable legends for multi-series charts 8. Test tooltips - Verify tooltip formatting with various data values

Common Patterns

Dynamic Series from Data

# Extract series names from data keys
data = [{"month": "Jan", "A": 100, "B": 200, "C": 150}, ...]

series_names = [k for k in data[0].keys() if k != "month"]
series = [{"name": name, "color": f"blue.{i}"} for i, name in enumerate(series_names)]

dmc.BarChart(data=data, dataKey="month", series=series)

Conditional Styling

# In assets/functions.js
dmcfuncs.colorByValue = (value) => {
    if (value > 1000) return 'green.7';
    if (value > 500) return 'yellow.6';
    return 'red.6';
};

# In Python
dmc.BarChart(
    getBarColor={"function": "colorByValue"},
    ...
)

Dash Fundamentals Reference

Comprehensive guide to Dash application architecture, state management, data sharing patterns, performance optimization, and best practices.

Table of Contents

1. Application Structure & Lifecycle 2. State Management with dcc.Store 3. Data Sharing Patterns 4. Performance Optimization 5. Callback Gotchas 6. Error Handling Best Practices

---

Application Structure & Lifecycle

Basic Dash App Structure

from dash import Dash, html, dcc, callback, Input, Output
import dash_mantine_components as dmc

# Initialize app
app = Dash(__name__)

# Define layout
app.layout = dmc.MantineProvider([
    html.Div([
        dcc.Store(id='session-data', storage_type='session'),
        dmc.Title("My Dash App", order=1),
        dmc.Button("Click Me", id="btn"),
        html.Div(id="output")
    ])
])

# Define callbacks
@callback(
    Output("output", "children"),
    Input("btn", "n_clicks"),
    prevent_initial_call=True
)
def update_output(n_clicks):
    return f"Clicked {n_clicks} times"

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

Callback Execution Lifecycle

Dash uses reactive programming - when inputs change, outputs automatically update:

1. Initial Load: All callbacks with outputs fire once (unless prevent_initial_call=True) 2. User Interaction: Input property changes trigger associated callbacks 3. Callback Execution: Dash collects current state of all Input/State properties 4. Output Update: Results update specified Output properties 5. Cascade: If outputs are inputs to other callbacks, those fire next

Key Principle: "It's sort of like programming with Microsoft Excel: whenever a cell changes (the input), all the cells that depend on that cell (the outputs) will get updated automatically."

Configuration Options

app = Dash(
    __name__,
    suppress_callback_exceptions=True,  # Allow dynamic layouts
    update_title=None,  # Disable "Updating..." in browser title
    assets_folder='assets',  # Custom assets directory
    background_callback_manager=background_callback_manager  # For long callbacks
)

# Additional config
app.config.prevent_initial_callbacks = True  # Global prevent_initial_call

---

State Management with dcc.Store

The dcc.Store component provides client-side JSON storage for sharing data between callbacks.

Storage Types

from dash import dcc

# Memory storage (default) - cleared on page refresh
dcc.Store(id='memory-store', storage_type='memory')

# Session storage - cleared when browser tab closes
dcc.Store(id='session-store', storage_type='session')

# Local storage - persists across browser sessions
dcc.Store(id='local-store', storage_type='local')

Key Properties

Storage Limitations

• Maximum size: 2MB in most environments, 5-10MB on desktop browsers
• Serialization: Data must be JSON-serializable
• Browser-specific: Limits vary by browser and device type

Basic Usage Pattern

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

app.layout = html.Div([
    dcc.Store(id='user-data', storage_type='session'),
    dcc.Dropdown(['A', 'B', 'C'], id='dropdown'),
    html.Div(id='output')
])

# Store data
@callback(
    Output('user-data', 'data'),
    Input('dropdown', 'value')
)
def store_selection(value):
    return {'selected': value, 'timestamp': time.time()}

# Retrieve data
@callback(
    Output('output', 'children'),
    Input('user-data', 'modified_timestamp'),
    State('user-data', 'data')
)
def display_data(ts, data):
    if data is None:
        return "No data stored"
    return f"Selected: {data['selected']}"

Initial Data Retrieval Pattern

Important: When using data as an output, you cannot access initial data via the data property. Use modified_timestamp as Input and data as State:

@callback(
    Output('display', 'children'),
    Input('store', 'modified_timestamp'),  # Trigger on changes
    State('store', 'data')  # Access the actual data
)
def display_data(ts, data):
    return f"Data: {data}"

Clearing Stored Data

@callback(
    Output('store', 'clear_data'),
    Input('reset-btn', 'n_clicks')
)
def clear_store(n_clicks):
    if n_clicks:
        return True
    return False

---

Data Sharing Patterns

Core Principle: No Global Variables

Critical Rule: "Dash Callbacks must never modify variables outside of their scope."

Why: Dash apps run across multiple workers whose memory is not shared. Modifying globals breaks multi-user deployments.

# ❌ WRONG - Do not modify global variables
df_filtered = df  # Global variable

@callback(Output('graph', 'figure'), Input('dropdown', 'value'))
def update_graph(value):
    global df_filtered  # NEVER DO THIS
    df_filtered = df[df['category'] == value]
    return px.line(df_filtered)

# ✅ CORRECT - Use local variables
@callback(Output('graph', 'figure'), Input('dropdown', 'value'))
def update_graph(value):
    df_filtered = df[df['category'] == value]  # Local variable
    return px.line(df_filtered)

Strategy 1: Browser Storage (dcc.Store)

Best for moderate datasets displayed across multiple components.

@callback(
    Output('filtered-data-store', 'data'),
    Input('filter-dropdown', 'value')
)
def filter_data(filter_value):
    filtered_df = df[df['category'] == filter_value]
    return filtered_df.to_dict('records')  # Serialize to JSON

@callback(
    Output('graph-1', 'figure'),
    Input('filtered-data-store', 'data')
)
def update_graph_1(data):
    df_filtered = pd.DataFrame(data)
    return px.bar(df_filtered, x='x', y='y')

@callback(
    Output('table', 'data'),
    Input('filtered-data-store', 'data')
)
def update_table(data):
    return data  # Already in dict format

Strategy 2: Server-Side Caching with Flask-Caching

Best for large datasets and expensive computations.

from flask_caching import Cache
import uuid

cache = Cache(app.server, config={
    'CACHE_TYPE': 'redis',
    'CACHE_REDIS_URL': os.environ.get('REDIS_URL', 'redis://localhost:6379')
})

# Or for development
cache = Cache(app.server, config={
    'CACHE_TYPE': 'filesystem',
    'CACHE_DIR': 'cache-directory'
})

app.layout = html.Div([
    dcc.Store(id='session-id', storage_type='session', data=str(uuid.uuid4())),
    # ... rest of layout
])

# Expensive computation with memoization
@cache.memoize()
def expensive_computation(session_id, filter_value):
    """Cache expensive operations by session ID and parameters."""
    # Simulate expensive operation
    time.sleep(5)
    filtered_df = df[df['category'] == filter_value]
    return filtered_df.to_dict('records')

@callback(
    Output('output', 'children'),
    Input('dropdown', 'value'),
    State('session-id', 'data')
)
def update_output(filter_value, session_id):
    # Retrieve from cache (fast) or compute (slow)
    data = expensive_computation(session_id, filter_value)
    return f"Processed {len(data)} records"

Strategy 3: Signaling Pattern

Use dcc.Store as a signal to coordinate callbacks, avoiding redundant computation.

app.layout = html.Div([
    dcc.Store(id='signal', data=0),
    dcc.Store(id='session-id', storage_type='session', data=str(uuid.uuid4())),
    dcc.Dropdown(['A', 'B', 'C'], id='filter'),
    html.Div(id='output-1'),
    html.Div(id='output-2'),
])

# Single callback performs expensive computation
@callback(
    Output('signal', 'data'),
    Input('filter', 'value'),
    State('session-id', 'data')
)
def compute_expensive_data(filter_value, session_id):
    # Expensive computation happens once
    filtered_data = expensive_computation(session_id, filter_value)
    cache.set(f'{session_id}-data', filtered_data)
    return filter_value  # Signal that computation is done

# Multiple callbacks retrieve cached results
@callback(
    Output('output-1', 'children'),
    Input('signal', 'data'),
    State('session-id', 'data')
)
def update_output_1(signal, session_id):
    data = cache.get(f'{session_id}-data')
    return f"Output 1: {len(data)} records"

@callback(
    Output('output-2', 'children'),
    Input('signal', 'data'),
    State('session-id', 'data')
)
def update_output_2(signal, session_id):
    data = cache.get(f'{session_id}-data')
    return f"Output 2: Processing complete"

---

Performance Optimization

1. Memoization for Expensive Functions

from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_data_processing(filter_value, category):
    """Cache function results in memory."""
    # Expensive operation
    result = df[df['cat'] == category].groupby('x').sum()
    return result.to_dict()

@callback(Output('graph', 'figure'), Input('dropdown', 'value'))
def update_graph(value):
    data = expensive_data_processing(value, 'A')
    return px.bar(data)

2. Efficient Serialization with orjson

For large data transfers, use orjson for faster JSON serialization:

import orjson
import pandas as pd

@callback(Output('store', 'data'), Input('btn', 'n_clicks'))
def store_large_dataset(n_clicks):
    large_df = pd.read_csv('large_file.csv')

    # Use orjson for fast serialization
    return orjson.loads(
        orjson.dumps(large_df.to_dict('records'))
    )

3. Data Aggregation Upfront

Minimize network traffic by pre-aggregating data:

@callback(
    Output('aggregated-store', 'data'),
    Input('filter', 'value')
)
def aggregate_data(filter_value):
    # ❌ Storing full dataset
    # return df.to_dict('records')  # Large payload

    # ✅ Store aggregated data
    aggregated = df.groupby('category').agg({
        'value': ['sum', 'mean', 'count']
    }).to_dict()
    return aggregated  # Much smaller payload

4. WebGL for Large Scatter Plots

Use WebGL rendering for better performance with large datasets:

import plotly.graph_objects as go

@callback(Output('scatter', 'figure'), Input('data-store', 'data'))
def update_scatter(data):
    df = pd.DataFrame(data)

    # Use Scattergl instead of Scatter for 100k+ points
    fig = go.Figure(
        data=go.Scattergl(
            x=df['x'],
            y=df['y'],
            mode='markers',
            marker=dict(size=5)
        )
    )
    return fig

5. Parallel Worker Processes

Configure multiple workers for concurrent user support:

# Gunicorn with 4 worker processes
gunicorn app:server --workers 4 --threads 2 --bind 0.0.0.0:8000

6. Clientside Callbacks for Frequent Updates

Move high-frequency callbacks to the browser:

from dash import clientside_callback, Input, Output

# JavaScript runs in browser - no server round-trip
clientside_callback(
    """
    function(n_intervals) {
        return new Date().toLocaleTimeString();
    }
    """,
    Output('clock', 'children'),
    Input('interval', 'n_intervals')
)

---

Callback Gotchas

1. Component Presence Requirement

Gotcha: All components referenced in callbacks must exist in the layout when the app starts.

# ❌ Component not in layout - callback will fail
@callback(Output('missing-component', 'children'), Input('btn', 'n_clicks'))
def update(n):
    return "text"

# ✅ For dynamic layouts, suppress validation
app.config.suppress_callback_exceptions = True

2. All Input/State Components Must Be Rendered

Gotcha: With validation suppressed, callbacks silently fail if components aren't rendered.

app.config.suppress_callback_exceptions = True

@callback(
    Output('output', 'children'),
    Input('conditional-input', 'value')  # May not exist
)
def update(value):
    # This callback won't fire if 'conditional-input' isn't rendered
    return f"Value: {value}"

# ✅ Solution: Use allow_optional (Dash 3.1+)
@callback(
    Output('output', 'children'),
    Input('conditional-input', 'value', allow_optional=True)
)
def update(value):
    if value is None:
        return "Component not present"
    return f"Value: {value}"

3. Callbacks Must Be Defined Before Server Starts

Gotcha: All callbacks must be defined before app.run().

# ❌ Cannot create callbacks dynamically after server starts
if __name__ == '__main__':
    app.run(debug=True)

    # This callback definition will be ignored
    @callback(Output('x', 'children'), Input('y', 'n_clicks'))
    def late_callback(n):
        return n

# ✅ Define all callbacks before app.run()
@callback(Output('x', 'children'), Input('y', 'n_clicks'))
def callback_func(n):
    return n

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

4. Circular Callbacks

Gotcha: Callbacks can create infinite loops if outputs feed back as inputs.

# ❌ Circular dependency can cause infinite loop
@callback(Output('input-1', 'value'), Input('input-2', 'value'))
def update_1(val):
    return val + 1

@callback(Output('input-2', 'value'), Input('input-1', 'value'))
def update_2(val):
    return val + 1

# ✅ Use prevent_initial_call and conditional logic
@callback(
    Output('input-1', 'value'),
    Input('input-2', 'value'),
    prevent_initial_call=True
)
def update_1(val):
    if val > 100:  # Break the loop
        raise PreventUpdate
    return val + 1

---

Error Handling Best Practices

1. Using PreventUpdate

Prevent callback execution when conditions aren't met:

from dash.exceptions import PreventUpdate

@callback(
    Output('output', 'children'),
    Input('btn', 'n_clicks'),
    State('input', 'value')
)
def update_output(n_clicks, value):
    # Don't update on initial load
    if n_clicks is None:
        raise PreventUpdate

    # Don't update if input is empty
    if not value:
        raise PreventUpdate

    return f"You entered: {value}"

2. Selective Updates with no_update

Update some outputs while leaving others unchanged:

from dash import no_update

@callback(
    Output('output-1', 'children'),
    Output('output-2', 'children'),
    Output('error-msg', 'children'),
    Input('input', 'value')
)
def multi_output(value):
    try:
        result = int(value)
        return f"Result: {result}", f"Squared: {result**2}", ""
    except ValueError:
        # Update only error message, leave other outputs unchanged
        return no_update, no_update, "Please enter a valid number"

3. Try-Except with User Feedback

@callback(
    Output('result', 'children'),
    Output('error-notification', 'children'),
    Input('submit-btn', 'n_clicks'),
    State('data-input', 'value')
)
def process_data(n_clicks, data):
    if not n_clicks:
        raise PreventUpdate

    try:
        # Attempt data processing
        result = expensive_computation(data)
        return f"Success: {result}", ""
    except FileNotFoundError as e:
        return no_update, dmc.Notification(
            title="File Not Found",
            message=str(e),
            color="red",
            action="show"
        )
    except Exception as e:
        return no_update, dmc.Notification(
            title="Processing Error",
            message=f"An error occurred: {str(e)}",
            color="red",
            action="show"
        )

4. Validation Before Processing

@callback(
    Output('output', 'children'),
    Input('submit-btn', 'n_clicks'),
    State('email-input', 'value'),
    State('age-input', 'value')
)
def submit_form(n_clicks, email, age):
    if not n_clicks:
        raise PreventUpdate

    errors = []

    # Validate email
    if not email or '@' not in email:
        errors.append("Valid email required")

    # Validate age
    try:
        age_int = int(age)
        if age_int < 0 or age_int > 120:
            errors.append("Age must be between 0 and 120")
    except (ValueError, TypeError):
        errors.append("Age must be a number")

    if errors:
        return dmc.Alert(
            "\n".join(errors),
            title="Validation Errors",
            color="red"
        )

    # Process valid data
    return dmc.Alert(
        f"Form submitted successfully for {email}",
        title="Success",
        color="green"
    )

5. Logging for Debugging

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@callback(
    Output('output', 'children'),
    Input('input', 'value')
)
def process_input(value):
    logger.info(f"Callback triggered with value: {value}")

    try:
        result = complex_operation(value)
        logger.info(f"Operation successful: {result}")
        return result
    except Exception as e:
        logger.error(f"Operation failed: {str(e)}", exc_info=True)
        return "An error occurred. Please try again."

---

References

Based on official Dash documentation:

• Advanced Callbacks
• Basic Callbacks
• Sharing Data Between Callbacks
• dcc.Store Component
• Callback Gotchas
• Performance