# filters

URL: /chirp-ui/api/filters/
Section: api
Description: Template filters required by chirp-ui components.

These match Chirp's filter API so chirp-ui works with any Chirp version.
Register via `register_filters`() when using Chirp.

Everything not in __all__ is internal and may change without notice.

---

> For a complete page index, fetch /chirp-ui/llms.txt.

# filters

Template filters required by chirp-ui components.

These match Chirp's filter API so chirp-ui works with any Chirp version.
Register via `register_filters`() when using Chirp.

Everything not in __all__ is internal and may change without notice.

module

Template filters required by chirp-ui components.

These match Chirp's filter API so chirp-ui works with any Chirp version.
Register via `register_filters`() when using Chirp.

Everything not in __all__ is internal and may change without notice.

reset_colors

function

Clear all registered semantic color names for the current context.

register_colors

function

Register semantic color names (e.g. Pokémon types) for `resolve_color`().

Raises ``ValueError`` immediately if any color value fails
`sanitize_color`() validation.

sanitize_color

function

Return the color if it matches a safe CSS color pattern, else None.

contrast_text

function

Return ``white`` or ``#1a1a1a`` for readable text on solid *css_color*.

Supports hex, ``rgb()``, ``hsl()``, and ``oklch()`` color formats.
Emits `ChirpUIValidationWarning` when the
color cannot be parsed (falls back to ``white``).

resolve_color

function

Resolve a named color from the registry, then validate as a CSS color string.

bem

function

Build chirpui BEM class string from block, axes, size, and modifiers.

Example::

class="{{ "btn" | bem(variant="primary", size="lg", modifier="loading") }}"
→ "chirpui-btn chirpui-btn--primary chirpui-btn--lg chirpui-btn--loading"

class="{{ "btn" | bem(appearance="outlined", tone="danger") }}"
→ "chirpui-btn chirpui-btn--outlined chirpui-btn--danger"

*modifier* accepts a single string or a list of strings for additive flags.

validate_variant

function

Return value if in allowed, else default.

Always emits `ChirpUIValidationWarning`
on fallback (raises ``ValueError`` in strict mode).

validate_variant_block

function

Return value if in VARIANT_REGISTRY for block, else default. When strict, log warning.

validate_appearance_block

function

Return value if in APPEARANCE_REGISTRY for block, else fallback.

validate_tone_block

function

Return value if in TONE_REGISTRY for block, else fallback.

deprecate_param

function

Warn when a deprecated parameter is used and return value unchanged.

Used in templates to signal deprecation while preserving backward compat::

{% set _attrs_raw = attrs_unsafe or (attrs | deprecate_param("attrs", "attrs_unsafe or attrs_map")) %}

value_type

function

Map Python types to ChirpUI CSS variant names for description_item.

Returns: "unset" | "bool" | "number" | "path" | "" (plain string).

validate_size

function

Return value if in SIZE_REGISTRY for block, else default.

Always emits `ChirpUIValidationWarning`
on fallback when the block has a registered size list
(raises ``ValueError`` in strict mode).

icon

function

Resolve icon name to glyph; unknown names pass through.

Always emits `ChirpUIValidationWarning`
for unrecognized names (raises ``ValueError`` in strict mode).

field_errors

function

Extract error messages for a field from a ValidationError-style dict.

Returns empty list if errors is None, not a dict, or field has no errors.
Expects ``errors[field_name]`` to be a list or tuple of strings.
Non-list values (e.g. nested dicts from DRF/Pydantic) are coerced to
``[str(val)]`` with a `ChirpUIValidationWarning`.

resolve_status_variant

function

Map a status string to a badge variant using `STATUS_WORDS`.

Lookup is case-insensitive. Unrecognized words return *default* and
emit `ChirpUIValidationWarning`.

build_hx_attrs

function

Build a dict of hyphenated HTML attributes from keyword arguments.

Converts underscores to hyphens in keys: ``hx_post`` becomes ``hx-post``.
Pipe through ``html_attrs`` to render: ``{{ build_hx_attrs(...) | html_attrs }}``.

Accepts an optional ``hx`` dict whose keys are the short htmx names
(e.g. ``{"post": "/save", "target": "#out"}`` → ``hx-post``, ``hx-target``).
Individual ``hx_*`` kwargs override keys from the ``hx`` dict.

Emits `ChirpUIValidationWarning` for
unrecognized htmx attribute names (possible typos). Event handlers
(``hx-on:*``) and non-``hx-`` keys pass through without warning.

check_required_id

function

Return *value* if provided, else *fallback* with a validation warning.

Use in macros where a hardcoded fallback ID would cause collisions
if multiple instances appear on the same page::

{% set _id = check_required_id(swap_id, "inline-edit-field", "inline_edit_field") %}

make_route_link_attrs

function

Build a template global for route-aware link attrs.

The default no-op version keeps standalone chirp-ui renderable. When
``swap_resolver`` is supplied (for example by Chirp's ``use_chirp_ui``),
internal ``href`` values can inherit route-aware ``hx-target`` / ``hx-boost``
attrs automatically.

html_attrs

function

Render HTML attrs from mapping or legacy raw string.

chirpui_asset_path

function

Return the Bengal logical asset path for a Chirp UI provider asset.