Gauge
A server-calculated SVG gauge for one value within a fixed range.
Try it
Health score
A labelled threshold gauge.
Use it
Working invocation
This code creates the configuration shown above. Copy the template and the required Python context together.
{% load brickwork_components %}
{% bw_gauge value=value label=label threshold_bands=health_bands %}context = {'health_bands': [{'max': 50, 'token': 'danger'}, {'max': 75, 'token': 'warning'}, {'max': 100, 'token': 'success'}], 'value': 73, 'label': 'Service health'}Guide
Add it to your project
- Load `brickwork_components`.
- Call `bw_gauge` with numeric `value`.
- Add label when adjacent content does not already name the gauge.
- Use threshold bands only for established semantic states.
Options
Public API
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
| value | number | Not set | Yes | Measured reading. Constraint: Use the same type and scale expected by the receiving form or measurement. |
| min | number | 0 | No | Range lower bound. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| max | number | 100 | No | Range upper bound. Constraint: Must exceed min. |
| label | str | Empty string | No | Accessible SVG name. Constraint: Use concise visible text that identifies the control or measurement. |
| size | str | md | No | Fixed diameter. Allowed: sm, md, lg. Constraint: Use one of the documented size choices; unsupported values are not a responsive substitute. |
| threshold_bands | list[dict] | Not set | No | Sorted bands of numeric max and token. Allowed: accent, success, warning, danger. Constraint: Bands use the documented bounds and must share the gauge measurement scale. |
| gauge_label | str|SafeString | Empty string | No | Trusted visible replacement for percentage. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| data | mapping | Not set | No | Consumer-owned data attributes. Constraint: Use the component's documented structured data shape; it is not a scalar visitor control. |
Behaviour
Accessibility and responsive behaviour
- Accessibility
- The SVG is named when labelled and always shows visible text, so arc length and colour never stand alone.
- Responsive
- Size is a fixed token scale with no breakpoint switch.
- Without JavaScript
- Pure server-rendered SVG; no JavaScript required.
Need help?
Troubleshooting
Contract check: {% include %}: min/max validation, value clamping, the percentage, the SVG
Use `{% bw_gauge %}` rather than a direct include so min/max validation, clamping, and percentage calculation occur in the tag.
Explore next