0
# Theme and Styling
1

2
Theme management system with comprehensive color palettes, typography settings, and Plotly integration for consistent styling across applications.
3

4
## Capabilities
5

6
### Theme Provider
7

8
Core theming system that provides styling context to all components.
9

10
```python { .api }
11
def MantineProvider(
12
    children=None,  # App components
13
    theme=None,  # Theme configuration object
14
    defaultColorScheme="light",  # "light" | "dark" | "auto"
15
    **kwargs
16
): 
17
    """
18
    Root theme provider for Mantine components.
19
    
20
    Parameters:
21
    - children: All application components must be wrapped
22
    - theme: Theme configuration object (uses DEFAULT_THEME if None)
23
    - defaultColorScheme: Default color scheme
24
    """
25

26
def TypographyStylesProvider(
27
    children=None,  # Content with typography
28
    **kwargs
29
): 
30
    """
31
    Provider for rich typography styles in user content.
32
    
33
    Parameters:
34
    - children: Content that needs typography styling
35
    """
36
```
37

38
### Default Theme Configuration
39

40
Complete theme object with all styling definitions.
41

42
```python { .api }
43
DEFAULT_THEME: dict = {
44
    # Core theme properties
45
    "scale": 1,
46
    "fontSmoothing": True,
47
    "focusRing": "auto",
48
    "white": "#fff",
49
    "black": "#000",
50
    
51
    # Color system
52
    "colors": {
53
        "dark": [...],  # Dark theme colors [0-9]
54
        "gray": [...],  # Gray scale [0-9]
55
        "red": [...],   # Red palette [0-9]
56
        "pink": [...],  # Pink palette [0-9]
57
        "grape": [...], # Grape/purple palette [0-9]
58
        "violet": [...],# Violet palette [0-9]
59
        "indigo": [...],# Indigo palette [0-9]
60
        "blue": [...],  # Blue palette [0-9]
61
        "cyan": [...],  # Cyan palette [0-9]
62
        "teal": [...],  # Teal palette [0-9]
63
        "green": [...], # Green palette [0-9]
64
        "lime": [...],  # Lime palette [0-9]
65
        "yellow": [...],# Yellow palette [0-9]
66
        "orange": [...] # Orange palette [0-9]
67
    },
68
    
69
    # Primary color configuration
70
    "primaryShade": {"light": 6, "dark": 8},
71
    "primaryColor": "blue",
72
    "autoContrast": False,
73
    "luminanceThreshold": 0.3,
74
    
75
    # Typography
76
    "fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, ...",
77
    "fontFamilyMonospace": "ui-monospace, SFMono-Regular, Menlo, Monaco, ...",
78
    "fontSizes": {
79
        "xs": "calc(0.75rem * var(--mantine-scale))",
80
        "sm": "calc(0.875rem * var(--mantine-scale))",
81
        "md": "calc(1rem * var(--mantine-scale))",
82
        "lg": "calc(1.125rem * var(--mantine-scale))",
83
        "xl": "calc(1.25rem * var(--mantine-scale))"
84
    },
85
    "lineHeights": {
86
        "xs": "1.4", "sm": "1.45", "md": "1.55", "lg": "1.6", "xl": "1.65"
87
    },
88
    
89
    # Spacing system
90
    "spacing": {
91
        "xs": "calc(0.625rem * var(--mantine-scale))",
92
        "sm": "calc(0.75rem * var(--mantine-scale))",
93
        "md": "calc(1rem * var(--mantine-scale))",
94
        "lg": "calc(1.25rem * var(--mantine-scale))",
95
        "xl": "calc(2rem * var(--mantine-scale))"
96
    },
97
    
98
    # Border radius
99
    "radius": {
100
        "xs": "calc(0.125rem * var(--mantine-scale))",
101
        "sm": "calc(0.25rem * var(--mantine-scale))",
102
        "md": "calc(0.5rem * var(--mantine-scale))",
103
        "lg": "calc(1rem * var(--mantine-scale))",
104
        "xl": "calc(2rem * var(--mantine-scale))"
105
    },
106
    
107
    # Responsive breakpoints
108
    "breakpoints": {
109
        "xs": "36em", "sm": "48em", "md": "62em", "lg": "75em", "xl": "88em"
110
    },
111
    
112
    # Shadow system
113
    "shadows": {
114
        "xs": "0 calc(0.0625rem * var(--mantine-scale)) ...",
115
        "sm": "0 calc(0.0625rem * var(--mantine-scale)) ...",
116
        "md": "0 calc(0.0625rem * var(--mantine-scale)) ...",
117
        "lg": "0 calc(0.0625rem * var(--mantine-scale)) ...",
118
        "xl": "0 calc(0.0625rem * var(--mantine-scale)) ..."
119
    },
120
    
121
    # Heading configuration
122
    "headings": {
123
        "fontFamily": "-apple-system, BlinkMacSystemFont, ...",
124
        "fontWeight": "700",
125
        "textWrap": "wrap",
126
        "sizes": {
127
            "h1": {"fontSize": "calc(2.125rem * var(--mantine-scale))", "lineHeight": "1.3"},
128
            "h2": {"fontSize": "calc(1.625rem * var(--mantine-scale))", "lineHeight": "1.35"},
129
            "h3": {"fontSize": "calc(1.375rem * var(--mantine-scale))", "lineHeight": "1.4"},
130
            "h4": {"fontSize": "calc(1.125rem * var(--mantine-scale))", "lineHeight": "1.45"},
131
            "h5": {"fontSize": "calc(1rem * var(--mantine-scale))", "lineHeight": "1.5"},
132
            "h6": {"fontSize": "calc(0.875rem * var(--mantine-scale))", "lineHeight": "1.5"}
133
        }
134
    },
135
    
136
    # Other configurations
137
    "respectReducedMotion": False,
138
    "cursorType": "default",
139
    "defaultGradient": {"from": "blue", "to": "cyan", "deg": 45},
140
    "defaultRadius": "sm",
141
    "activeClassName": "mantine-active",
142
    "focusClassName": "",
143
    "other": {},
144
    "components": {}
145
}
146
"""
147
Complete Mantine theme configuration with all styling properties.
148
Includes color palettes, typography, spacing, shadows, and component defaults.
149
"""
150
```
151

152
### Plotly Integration
153

154
Figure template utilities for consistent chart styling.
155

156
```python { .api }
157
def add_figure_templates(default=None):
158
    """
159
    Create and register Plotly figure templates styled to match Mantine theme.
160
    
161
    Creates two templates:
162
    - "mantine_light": Light mode styling
163
    - "mantine_dark": Dark mode styling
164
    
165
    Parameters:
166
    - default: str, optional
167
        Set default template ("mantine_light" or "mantine_dark")
168
        If None, default Plotly template unchanged
169
        
170
    Returns:
171
    - None: Templates registered with plotly.io.templates
172
    
173
    Raises:
174
    - ValueError: If default is not a valid template name
175
    
176
    Usage:
177
    - add_figure_templates()  # Register templates
178
    - add_figure_templates("mantine_light")  # Set as default
179
    """
180
```
181

182
### Legacy Styles Module
183

184
Backward compatibility module for older versions.
185

186
```python { .api }
187
# Style constants (backward compatibility)
188
styles.ALL: list = []  # Empty list, CSS now bundled
189
styles.DATES: str = ""  # Empty string
190
styles.CODE_HIGHLIGHT: str = ""
191
styles.CHARTS: str = ""
192
styles.CAROUSEL: str = ""
193
styles.NOTIFICATIONS: str = ""
194
styles.NPROGRESS: str = ""
195
styles.RICH_TEXT_EDITOR: str = ""
196
"""
197
Legacy style imports for backward compatibility.
198
As of v1.2.0, CSS is bundled with components.
199
"""
200
```
201

202
## Theme Configuration Types
203

204
```python { .api }
205
# Color palette structure (10 shades per color)
206
ColorPalette = List[str]  # ["#lightest", ..., "#darkest"]
207

208
# Complete color system
209
ColorSystem = Dict[str, ColorPalette]  # {"blue": [...], "red": [...]}
210

211
# Size scale for spacing, fonts, etc.
212
SizeScale = Dict[str, str]  # {"xs": "0.5rem", "sm": "0.75rem", ...}
213

214
# Responsive breakpoint configuration
215
Breakpoints = Dict[str, str]  # {"xs": "36em", "sm": "48em", ...}
216

217
# Theme configuration object
218
class ThemeConfig:
219
    colors: ColorSystem
220
    primaryColor: str
221
    primaryShade: Dict[str, int]  # {"light": 6, "dark": 8}
222
    fontFamily: str
223
    fontSizes: SizeScale
224
    spacing: SizeScale
225
    radius: SizeScale
226
    shadows: SizeScale
227
    breakpoints: Breakpoints
228
    headings: Dict[str, Any]
229
    # ... other theme properties
230
```
231

232
## Usage Examples
233

234
### Basic Theme Setup
235

236
```python
237
import dash_mantine_components as dmc
238

239
# Basic app with default theme
240
app.layout = dmc.MantineProvider([
241
    dmc.Container([
242
        dmc.Title("My App", order=1),
243
        dmc.Text("Styled with default Mantine theme"),
244
        dmc.Button("Primary Button", color="blue")
245
    ])
246
])
247
```
248

249
### Custom Theme Configuration
250

251
```python
252
# Custom theme extending default
253
custom_theme = {
254
    **dmc.DEFAULT_THEME,  # Start with default theme
255
    "primaryColor": "teal",  # Change primary color
256
    "fontFamily": "Inter, -apple-system, sans-serif",  # Custom font
257
    "components": {
258
        "Button": {
259
            "styles": {
260
                "root": {
261
                    "fontWeight": 600,
262
                    "borderRadius": "8px"
263
                }
264
            }
265
        }
266
    }
267
}
268

269
app.layout = dmc.MantineProvider([
270
    # Your app content
271
], theme=custom_theme)
272
```
273

274
### Dark Mode Support
275

276
```python
277
import dash_mantine_components as dmc
278
from dash import Input, Output, callback
279

280
# App with theme switching
281
app.layout = dmc.MantineProvider([
282
    dmc.Container([
283
        dmc.Group([
284
            dmc.Title("Theme Demo"),
285
            dmc.Switch(
286
                id="color-scheme-switch",
287
                label="Dark Mode",
288
                size="lg"
289
            )
290
        ], position="apart"),
291
        
292
        dmc.Paper([
293
            dmc.Text("This content adapts to the theme"),
294
            dmc.Button("Themed Button")
295
        ], p="md", shadow="sm")
296
    ])
297
], id="theme-provider", defaultColorScheme="light")
298

299
@callback(
300
    Output("theme-provider", "forceColorScheme"),
301
    Input("color-scheme-switch", "checked")
302
)
303
def switch_theme(checked):
304
    return "dark" if checked else "light"
305
```
306

307
### Plotly Chart Integration
308

309
```python
310
import dash_mantine_components as dmc
311
import plotly.express as px
312

313
# Setup Mantine figure templates
314
dmc.add_figure_templates("mantine_light")
315

316
# Create chart with Mantine styling
317
df = px.data.iris()
318
fig = px.scatter(
319
    df, x="sepal_width", y="sepal_length", 
320
    color="species", template="mantine_light"
321
)
322

323
chart_layout = dmc.MantineProvider([
324
    dmc.Container([
325
        dmc.Title("Chart with Mantine Theme"),
326
        dmc.Paper([
327
            dcc.Graph(figure=fig)
328
        ], p="md", shadow="sm")
329
    ])
330
])
331
```
332

333
### Responsive Design with Breakpoints
334

335
```python
336
# Responsive layout using theme breakpoints
337
responsive_layout = dmc.Container([
338
    dmc.SimpleGrid([
339
        dmc.Paper("Item 1", p="md"),
340
        dmc.Paper("Item 2", p="md"), 
341
        dmc.Paper("Item 3", p="md"),
342
        dmc.Paper("Item 4", p="md")
343
    ], 
344
    # Responsive columns using theme breakpoints
345
    cols={"base": 1, "sm": 2, "md": 3, "lg": 4},
346
    spacing="md")
347
])
348
```
349

350
### Typography Styling
351

352
```python
353
# Rich typography content
354
typography_demo = dmc.TypographyStylesProvider([
355
    dmc.Container([
356
        # This HTML content will be styled with Mantine typography
357
        html.Div([
358
            html.H1("Main Heading"),
359
            html.H2("Subheading"),
360
            html.P("This is a paragraph with styled typography."),
361
            html.Ul([
362
                html.Li("List item 1"),
363
                html.Li("List item 2")
364
            ]),
365
            html.Blockquote("This is a styled blockquote.")
366
        ])
367
    ])
368
])
369
```
370

371
### Color System Usage
372

373
```python
374
# Using theme colors in components
375
color_demo = dmc.Stack([
376
    dmc.Group([
377
        dmc.Button("Blue", color="blue"),
378
        dmc.Button("Green", color="green"),
379
        dmc.Button("Red", color="red"),
380
        dmc.Button("Orange", color="orange")
381
    ]),
382
    
383
    dmc.Group([
384
        dmc.Badge("Info", color="blue", variant="light"),
385
        dmc.Badge("Success", color="green", variant="light"),
386
        dmc.Badge("Warning", color="yellow", variant="light"),
387
        dmc.Badge("Error", color="red", variant="light")
388
    ]),
389
    
390
    # Direct color usage
391
    dmc.Text("Custom colored text", c="teal.6"),  # teal shade 6
392
    dmc.Paper("Colored background", bg="gray.1", p="md")
393
])
394
```