FilterBuilder

Implemented Input

Reusable filter editor with AND conditions, typed values, draft/apply semantics and a JSON form contract.

A wdj composition built from the existing component library.

Presentation commands show demo feedback. Read the interaction guide to connect real actions.

Filter conditions

Choose fields, operators and values, combine conditions with AND, then apply or cancel the draft.

Request filters

No filters applied.

Show template

{% load wdj %}
<div class="flex w-full flex-col gap-4" x-data="{ message: 'No filters applied.' }" @wdj:filters-change="message = $event.detail.conditions.length ? $event.detail.conditions.length + ($event.detail.conditions.length === 1 ? ' condition applied.' : ' conditions applied.') : 'No filters applied.'">
  <div class="flex flex-wrap items-center justify-between gap-3">
    <p class="text-base font-medium">Request filters</p>
    {% include "wdj/components/filter_builder.html" with id="request-filters" fields=filter_fields only %}
  </div>
  <p class="text-base text-kumo-subtle" aria-live="polite" x-text="message">No filters applied.</p>
</div>

Form integration

Initial conditions, a three-condition limit, a JSON form value and native reset.

Show template

{% load wdj %}
<form class="flex w-full flex-col gap-4" x-data="{ submitted: '' }" @submit.prevent="submitted = new FormData($el).get('filters')" @reset="submitted = ''">
  <div class="flex flex-wrap items-center gap-3">
    {% include "wdj/components/filter_builder.html" with id="form-filters" name="filters" fields=filter_fields value=filter_initial label="Edit filters" max_conditions=3 only %}
    {% include "wdj/components/button.html" with label="Submit form" type="submit" variant="secondary" only %}
    {% include "wdj/components/button.html" with label="Reset" type="reset" variant="ghost" only %}
  </div>
  <p class="text-base text-kumo-subtle">Apply commits the draft to the form. Cancel discards it. Reset restores the initial conditions.</p>
  <output class="block min-w-0 break-words font-mono text-sm text-kumo-subtle" aria-live="polite" x-text="submitted || 'Submit to inspect the form value.'">Submit to inspect the form value.</output>
</form>

API Reference

Prop	Type	Default	Description
fields	list[dict]	unset	FilterBuilder: {value, label, type: text\|number\|select, options: [{value, label}], operators: [supported operator keys]}.
value	dict: {match, conditions}	{"match":"all","conditions":[]}	Value; pass the documented value shown in the examples.
name	string	filters	Name; pass the documented value shown in the examples.
id	string	unset	Stable unique DOM ID; important for HTMX targets and focus restoration.
label	string	Add filter	Visible accessible label. Supply an explicit aria-label via attrs when the control is bare.
max_conditions	number	10	FilterBuilder: maximum draft conditions, default 10, clamped to 1–100.
disabled	bool	False	Disabled; pass the documented value shown in the examples.
class	string	""	Class; pass the documented value shown in the examples.

Accessibility notes

Every interactive component keeps real semantics and keyboard support: native controls where possible, ARIA only where necessary, and a visible focus ring. See the Accessibility page for the shared contract.

Read the accessibility contract