Empty state
A purposeful no-data or no-results state with optional recovery action.
Try it
No matching results
A filter recovery state.
Use it
Working invocation
This code creates the configuration shown above. Copy the template and the required Python context together.
{% include "brickwork/components/_empty_state.html" with heading=heading body=body variant=variant action_href="/projects/" action_label=action_label %}context = {'heading': 'No matching projects', 'body': 'Try removing a filter or changing your search.', 'variant': 'no_results', 'action_label': 'Clear filters'}Guide
Add it to your project
- Supply body at every size and heading at the default size.
- Choose `no_data` for first-use onboarding or `no_results` for an empty filter result.
- Include simple copy or extend named regions for rich content.
Options
Public API
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
| heading | str | Not set | Yes | State heading; optional only at size sm. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| body | str | Not set | Yes | Explanation; required at all sizes. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| variant | str | no_data | No | Empty-state intent. Allowed: no_data, no_results. Constraint: Use one of the documented variants; use `danger`, not an invented `error` severity. |
| icon | str | Not set | No | Registered decorative icon. Constraint: No additional package-level validation is documented beyond this option's stated type and its role in the component. |
| action_href | str | Not set | No | Recovery action URL. Constraint: Provide this only with its matching action label and a valid destination. |
| action_label | str | Not set | No | Recovery action text. Constraint: Provide this only with its matching action URL and make the result clear. |
| size | str | md | No | Panel scale. Allowed: sm, md. Constraint: Use one of the documented size choices; unsupported values are not a responsive substitute. |
| surface | str | framed | No | Frame treatment. Allowed: framed, plain. Constraint: Use one of the documented surface choices; do not set a consumer CSS class as a substitute. |
Named blocks
Fill these only when you extend the component template. They are not values passed to an include or tag.
| Block | What it replaces |
|---|---|
| icon | Custom icon region. Constraint: Markup-only extension seam; passing a context variable with this name is ignored. |
| heading | Custom heading region. Constraint: Markup-only extension seam; passing a context variable with this name is ignored. |
| body | Custom body region. Constraint: Markup-only extension seam; passing a context variable with this name is ignored. |
| action | Custom action region. Constraint: Markup-only extension seam; passing a context variable with this name is ignored. |
Behaviour
Accessibility and responsive behaviour
- Accessibility
- Text conveys the outcome and icons are decorative. The md heading is h2 while small embedded states use a paragraph.
- Responsive
- No breakpoint switch; sm is an explicit embedded-panel scale.
- Without JavaScript
- Static recovery link works without JavaScript.
Need help?
Troubleshooting
Contract check: Required context: heading (except at size="sm", see below), body (required at
Supply both heading and body at the normal scale; the compact `sm` form is the documented exception for the heading.
Explore next