bjornmelin/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

| Need | Component | Key Props | |------|-----------|-----------| | Text input | TextInput | label, placeholder, value, debounce | | Dropdown | Select | data, value, searchable, clearable | | Multi-select | MultiSelect | data, value, searchable | | Checkbox | Checkbox | label, checked | | Toggle | Switch | label, checked, onLabel, offLabel | | Number | NumberInput | value, min, max, step | | Date | DatePickerInput | value, type, minDate, maxDate | | Rich text | Textarea | label, value, autosize, minRows | | File upload | FileInput | value, accept, multiple |

Layout

| Need | Component | Key Props | |------|-----------|-----------| | Content wrapper | Container | size, px, py | | Vertical stack | Stack | gap, align, justify | | Horizontal row | Group | gap, justify, wrap | | CSS Grid | Grid, GridCol | columns, gutter, span | | Full app shell | AppShell | header, navbar, aside, footer | | Card container | Card | shadow, padding, radius, withBorder | | Flex layout | Flex | direction, wrap, gap, align |

Navigation

| Need | Component | Key Props | |------|-----------|-----------| | Nav item | NavLink | label, href, active, leftSection | | Tabs | Tabs, TabsList, TabsPanel | value, orientation | | Breadcrumb | Breadcrumbs | separator | | Stepper | Stepper, StepperStep | active, onStepClick | | Pagination | Pagination | value, total, siblings | | Table of contents | TableOfContents | links, variant, active |

Feedback & Overlays

| Need | Component | Key Props | |------|-----------|-----------| | Modal dialog | Modal | opened, onClose, title, centered | | Side panel | Drawer | opened, onClose, position, size | | Toast | Notification | title, message, color, icon | | Alert banner | Alert | title, color, variant, icon | | Loading | Loader, LoadingOverlay | size, type, visible | | Progress | Progress, RingProgress | value, size, sections | | Tooltip | Tooltip | label, position, withArrow | | Copy button | CopyButton | value, timeout |

Data Display

| Need | Component | Key Props | |------|-----------|-----------| | Data table | Table | data, striped, highlightOnHover | | Accordion | Accordion, AccordionItem | value, multiple, variant | | Timeline | Timeline, TimelineItem | active, bulletSize | | Badge | Badge | color, variant, size |

Charts

| Need | Component | Key Props | |------|-----------|-----------| | Line | LineChart | data, dataKey, series | | Bar | BarChart | data, dataKey, series, orientation | | Area | AreaChart | data, dataKey, series | | Pie/Donut | DonutChart, PieChart | data, chartLabel | | Scatter | ScatterChart | data, dataKey, series |

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:

| Prop | CSS Property | Values | |------|--------------|--------| | m, mt, mb, ml, mr, mx, my | margin | xs, sm, md, lg, xl or number (px) | | p, pt, pb, pl, pr, px, py | padding | same as margin | | c | color | "blue", "red.6", "dimmed", "var(--mantine-color-text)" | | bg | background | same as color | | w, h | width, height | "100%", "50vw", number (px) | | maw, mah, miw, mih | max/min width/height | same as w, h | | fw | font-weight | 400, 500, 700 | | fz | font-size | xs, sm, md, lg, xl or number | | ta | text-align | "left", "center", "right" | | td | text-decoration | "underline", "line-through" |

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:

| Category | Components | Reference | |----------|------------|-----------| | All Components | 90+ components with props/events | components-quick-ref.md | | Theming | MantineProvider, theme object, colors | theming-patterns.md | | Styling | Style props, Styles API, CSS variables | styling-guide.md | | Callbacks | Pattern-matching, clientside, background | callbacks-advanced.md | | Multi-Page | Dash Pages, routing, AppShell | multi-page-apps.md | | Charts | Data formats, series config | charts-data-formats.md | | Date Pickers | DatePicker, DatesProvider, localization | date-pickers-guide.md | | Dash Core | dcc.Store, caching, performance | dash-fundamentals.md | | Migration | v1.x to v2.x breaking changes | migration-v2.md |

Asset Templates

Copy and adapt these templates:

| Template | Description | |----------|-------------| | app_single_page.py | Complete single-page DMC app with theme toggle | | app_multi_page.py | Multi-page app with Dash Pages and AppShell | | callbacks_patterns.py | All callback pattern examples | | theme_presets.py | Pre-built theme configurations |

Utility Scripts

| Script | Usage | |--------|-------| | fetch_docs.py | python fetch_docs.py "Select" - Fetch/search official llms.txt | | scaffold_app.py | python scaffold_app.py myapp --type multi --shell | | generate_theme.py | python generate_theme.py --primary "#0ea5e9" | | component_search.py | python component_search.py "select" |

---

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

| Error | Cause | Fix | |-------|-------|-----| | MantineProvider is required | Component outside provider | Wrap entire layout in dmc.MantineProvider([...]) | | Invalid theme color | Color not in theme | Use built-in colors (blue, red) or add to theme["colors"] | | Callback output not found | Component not in layout | Ensure component with ID exists in layout | | Circular callback detected | Output also used as Input | Use State instead of Input for non-triggering values | | Pattern-matching ID mismatch | Dict keys don't match | Ensure type and index keys match exactly | | Duplicate callback outputs | Same output in multiple callbacks | Add allow_duplicate=True to additional callbacks |

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