Theme switch
A client-side root theme, density, direction and optional brand axis control.
Try it
Compact header control
Theme and density switch in a header.
Use it
Working invocation
This code creates the configuration shown above. Copy the template and the required Python context together.
{% load brickwork_theming %}
{% bw_theme_switch axes="theme density" layout=layout placement=placement id="display-settings" %}context = {'layout': 'compact', 'placement': 'end'}Guide
Add it to your project
- Load `brickwork_theming` and include the theme context processor.
- Call `bw_theme_switch`; choose compact layout for header actions.
- Supply `brands` whenever `axes` includes brand.
Options
Public API
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
| axes | space-separated string | theme density dir | No | Enabled axes. Allowed: theme, density, dir, brand. Constraint: Use supported shell axes only; host policy may lock axes through `locked_axes`. |
| brands | mapping | Not set | No | Required for brand axis; slug to display label. Constraint: Brand records must be supplied by the host's validated theme resolver. |
| label | string | Display settings | No | Control accessible name. Constraint: Use concise visible text that identifies the control or measurement. |
| locked_axes | space-separated string | Not set | No | Read-only axes; omitted reads theme context. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| layout | string | inline | No | Presentation. Allowed: inline, compact. Constraint: Allowed values: `inline`, `compact`. |
| placement | string | end | No | Compact panel edge. Allowed: start, end. Constraint: Only valid with compact layout. |
| data | mapping | Not set | No | Consumer data-* attributes. Constraint: Use the component's documented structured data shape; it is not a scalar visitor control. |
| id | string | Not set | No | Stable id-safe instance token. Constraint: Use a stable id-safe token of letters, digits, hyphens, or underscores; it must be unique on the page. |
Behaviour
Accessibility and responsive behaviour
- Accessibility
- Each axis is a fieldset/legend; locked values are disabled. Compact uses native details/summary.
- Responsive
- Compact panel is anchored logically; pre-init reserves its layout box.
- Without JavaScript
- By design it remains invisible without JS because an apparently working control would be misleading.
Need help?
Troubleshooting
Contract check: (templatetags/brickwork_theming.py): never {% include %} directly, the tag
Use the theme-switch tag so it validates axes, resolves option groups, and applies host lock state.