Quick Filters

What It Is

Quick filters are small, pre-defined filter controls that you place directly into a view's layout. Instead of forcing a user through the full add filter → pick column → open the filter form → set the value → apply flow, a quick filter exposes a single, purpose-built control — a toggle, a search box, a row of preset buttons, or a set of checkboxes — that applies a known filter the moment it is used.

A quick filter is defined once by the implementer (in the view's Layout builder), stored as part of the view's layout configuration, and rendered wherever you drop it: in a view zone (header, before-data, etc.) or inside the filters bar.

Why It Matters

Most real views have a handful of filters that users reach for constantly: only active records, due this week, status = open, search by name. Re-deriving those from scratch every time is slow and error-prone.

Quick filters turn those recurring intents into one-click or one-keystroke controls:

• they remove repetitive multi-step interactions for the most common filters
• they let you present filtering in business language ("Only mine") instead of raw operators
• they keep the underlying query clean — a quick filter does not create a saved query and does not clutter the query list
• they survive pagination and reload like any other view state

Use quick filters when a filter is predictable, frequently used, and benefits from a dedicated control. Keep the full filter UI for ad-hoc, exploratory filtering.

Mental Model

Think of a quick filter in three parts:

1. A control — how it looks and behaves (renderType: toggle, search, preset, checkbox).
2. A contribution — the filter (or filters) it applies to the underlying query when it is active.
3. A placement — where it renders in the layout (a view zone, a filter zone, or unused).

When a user interacts with the control, the quick filter contributes its filter to the view's query as a fixed, system-applied filter:

• it is combined with the view's base query and any manual filters using AND
• it does not appear as an editable filter chip in the active-filters row (it is owned by the control, not the user)
• its on/off/value state is carried in the view's share state, so it persists across paging, sorting, and full reloads, and can be captured in shareable view links

This is the key difference from a saved query: a quick filter layers a filter on top of the current query at runtime, rather than defining a new query object.

Where Quick Filters Live

Quick filters are configured in the view Layout builder and stored inside the view's settings.layout configuration (per viewer). You never edit that storage directly in normal use — the builder reads, validates, and writes it for you. See Views for the surrounding view configuration and the settings field.

Two authoring surfaces exist in the layout builder, and they are intentionally symmetric with custom buttons:

• a top-level Quick filters manager (toolbar button) that lists every quick filter in the view and lets you create, edit, place, suspend, and delete them
• a ✎ pencil on each placed quick-filter item in the builder canvas, which opens the same manager focused on that item

The Two Editing Modes

Every quick filter is authored in one of two modes. The manager exposes a single Edit as JSON switch to move between them.

Guided mode

The default. You choose a component type, a property, a condition, and (depending on the type) a value, presets, or options. The builder reads the property's family to offer the operators and presets that property actually supports, and writes a clean definition for you.

Use guided mode for the common cases: a toggle on a boolean, a text search on a name, preset buttons over a status enumeration, checkboxes over a small option set.

JSON mode

The escape hatch. The full quick-filter definition is exposed as an editable JSON object, and you can also switch definitionMode to raw to express the contribution in the same notation the REST API uses. Use JSON mode when:

• you need an operator or argument shape the guided picker does not surface (for example between, in, subquery operators)
• you want to apply several filters at once, or an OR chain, from a single control
• you are copying a definition between views

The rest of this chapter documents the JSON structure exhaustively. Guided mode produces the same structure, so understanding the JSON helps even if you rarely edit it by hand.

Render Types

The renderType decides the control and how the active value is shaped.

toggle

A single on/off button. When on, it applies one fixed filter; when off, it removes it. No user input.

Use for binary intents: Only active, Has attachment, Assigned to me.

search

A text input bound to a property. The typed text becomes the filter value (typically contains). Supports a submit mode (button / Enter) and a live mode (debounced as you type).

Use for free-text lookups on a single column.

preset

A single-select row of buttons (or pills). Each option carries its own value; selecting one applies that option's filter, selecting it again clears it. Only one option is active at a time.

Use for mutually exclusive choices: a status switch, a date-range selector.

checkbox

A multi-select set. Each option toggles independently; the selected set is combined with OR or AND.

Use when several values can be active together: multiple statuses, multiple tags-like categories.

Placement

Each quick filter has a placement, chosen in the manager's Zone dropdown or by dragging the item in the builder:

• View zones — header areas, before/after data, etc. (depends on the viewer)
• Filter zones — inside the filters bar (query_row, tools_row, active_row, actions_row)
• Unused (suspended) — kept in the configuration but not rendered

Suspending is the way to park a quick filter without deleting it. A suspended quick filter is preserved exactly, contributes nothing to the query, and renders nowhere — until you place it back into a zone. You can also drag a quick-filter item into the builder's "unused components" palette to suspend it.

See Views for the available zones per viewer.

How A Quick Filter Affects The Query

When a quick filter is active, its contribution is applied as a fixed filter on the view's query for that request:

• AND with everything else — it combines with the base query, the default query, and any manual filters. If the base query already filters the same property, both conditions apply.
• Hidden from active-filter chips — because the control owns it, it is not shown as a removable chip and cannot be edited from the active-filters row.
• No saved query created — the contribution is layered at runtime; your query list stays clean.
• State round-trips — the control's on/off/value is stored in the view share state and re-applied on paging, sorting, refresh, and reload.

Because contributions are fixed and combined with AND, design quick filters to narrow a result set predictably. If you need a control that broadens or replaces scope, prefer a query selector or a saved query.

JSON Definition Reference

This section documents every field of a quick-filter definition. This is exactly what you see and edit in Edit as JSON mode. Guided mode writes the same object.

Top-level fields

Presentation fields (separateRow, customCss, backgroundColor, borderColor, borderRadius, padding, marginLeft) may also be present; they mirror the layout-component styling options described in Views.

Required fields per render type

• toggle — propertyId + filterType (+ filterParams for value-bearing operators), or raw.
• search — propertyId (+ search.filterType), or raw.
• preset / checkbox — propertyId + filterType + options (each option a value), or per-option raw.

Conditions (filterType)

filterType is the operator. Which operators are valid depends entirely on the property's family — quick filters do not invent their own operator set. Always confirm against Filter Operators.

The guided picker offers a safe, single-value subset per family:

In JSON / raw mode you may use any operator the family supports, including multi-value ones (between, in, in_list, in_subquery, …). For multi-value operators, raw mode is usually the cleaner choice.

Operators that take no value — null, not_null, true, false — use an empty filterParams ({}).

filterParams

In guided mode, filterParams carries the operator's argument(s), keyed by the operator name:

• single-value operator: { "<filterType>": <value> }
  • filterType: "equal" → { "equal": "1" }
  • filterType: "contains" → { "contains": "invoice" }
  • filterType: "greater_than" → { "greater_than": 100 }
• preset operator: { "preset": "<presetKey>" } → { "preset": "thisWeek" }
• no-value operator: {}

Date presets

When filterType is preset, the value is a preset key. Built-in date presets:

today, tomorrow, yesterday, thisWeek, last7days, thisMonth, last30days, previousMonth, previous3months, thisYear, futureInclToday, futureExclToday, pastInclToday, pastExclToday.

Presets are timezone-aware and evaluated at request time. Prefer them over hand-written date boundaries. See Date filter operators.

options (preset and checkbox)

options is an array of selectable choices. Two shapes are supported:

• Guided option — a value fed into the parent propertyId + filterType, plus a display label:

  { "value": "open", "label": "Open" }
  

• Raw option — its own contribution in REST notation:

  { "label": "Overdue", "raw": { "filters": [ { "property": "due", "type": "less_than", "param": "{{today}}" } ] } }
  

For a date property, the "Load from property" helper fills options from the date presets and sets filterType to preset, so each button applies a preset (e.g. Today, This week).

For checkbox, multiSelectCombine controls how the selected options combine:

• or — the control emits a single filter whose option values are OR-linked (match any selected)
• and — each selected option applies as a separate AND filter (match all selected)

search (search type)

"search": { "mode": "submit", "filterType": "contains", "debounceMs": 300 }

• mode — submit (apply on Enter / the search button) or live (apply automatically while typing)
• filterType — the operator the typed text uses (typically contains; is/equal for exact match)
• debounceMs — for live mode, the idle delay before applying (default 300)

Raw mode (the escape hatch)

Set definitionMode to raw and provide raw.filters. Each entry uses the same notation the REST API accepts (see Query Parameters and REST API):

{ "property": "<propertyId or path>", "type": "<operator>", "param": <value>, "or": [ … ] }

• property — the property id; dotted paths (e.g. owner.email) target nested properties of a relation
• type — any operator the property family supports
• param — the operator argument (string, number, or list; omit for no-value operators)
• or — an optional list of additional filter entries that are OR-linked with this one

The {{value}} placeholder. In raw filters, {{value}} is substituted with the control's active value at request time. This is how a search control feeds its typed text into a raw filter:

{ "property": "name", "type": "contains", "param": "{{value}}" }

For a toggle, the active value is 1 when on; for preset / checkbox, use per-option raw instead of {{value}}.

Raw mode is the right tool for: multi-value operators (between, in), OR chains, nested-property filters, or applying more than one condition from one control.

Worked examples

Toggle — only active (boolean), guided

{
  "renderType": "toggle",
  "label": "Only active",
  "variant": "primary",
  "definitionMode": "guided",
  "propertyId": "is_active",
  "filterType": "true",
  "filterParams": {}
}

Toggle — due this week (date preset), guided

{
  "renderType": "toggle",
  "label": "Due this week",
  "icon": "bi bi-calendar-week",
  "definitionMode": "guided",
  "propertyId": "due_date",
  "filterType": "preset",
  "filterParams": { "preset": "thisWeek" }
}

Search — by name, live, guided

{
  "renderType": "search",
  "label": "Search name…",
  "definitionMode": "guided",
  "propertyId": "name",
  "search": { "mode": "live", "filterType": "contains", "debounceMs": 250 }
}

Preset — status switch (enumeration), guided

{
  "renderType": "preset",
  "label": "Status",
  "definitionMode": "guided",
  "propertyId": "status",
  "filterType": "is",
  "options": [
    { "value": "open", "label": "Open" },
    { "value": "in_progress", "label": "In progress" },
    { "value": "closed", "label": "Closed" }
  ]
}

Checkbox — multiple priorities, OR, guided

{
  "renderType": "checkbox",
  "label": "Priority",
  "definitionMode": "guided",
  "propertyId": "priority",
  "filterType": "is",
  "multiSelectCombine": "or",
  "options": [
    { "value": "high", "label": "High" },
    { "value": "medium", "label": "Medium" },
    { "value": "low", "label": "Low" }
  ]
}

Toggle — raw escape hatch (this week via preset, raw notation)

{
  "renderType": "toggle",
  "label": "This week",
  "definitionMode": "raw",
  "raw": { "filters": [ { "property": "due_date", "type": "preset", "param": "thisWeek" } ] }
}

Search — raw with {{value}} and an OR across two columns

{
  "renderType": "search",
  "label": "Search…",
  "definitionMode": "raw",
  "search": { "mode": "submit", "filterType": "contains", "debounceMs": 300 },
  "raw": { "filters": [
    { "property": "name", "type": "contains", "param": "{{value}}",
      "or": [ { "property": "email", "type": "contains", "param": "{{value}}" } ] }
  ] }
}

Advanced Template Shortcode

If the view uses the advanced (custom-HTML) layout template instead of zone placement, quick filters are inserted with a shortcode:

[[quickfilter.<view|filters>.<zone>.<id>]]

For example [[quickfilter.view.before_data.qf_status]]. The advanced editor's palette lists every quick filter you have defined so you can click to insert it. See the advanced template section of Views.

Best Practices

• Keep each quick filter single-purpose. A toggle should mean one thing. Reach for preset/checkbox when there is a small, known set of choices.
• Prefer guided mode unless you genuinely need a multi-value operator, an OR chain, or nested-property targeting — then use raw mode.
• Use presets for dates rather than hand-written boundaries; they are timezone-correct and self-documenting.
• Confirm operators against the property family. A condition that the family does not support will not match anything. See Filter Operators.
• Place high-traffic filters in a visible zone (header or tools_row); suspend the rest instead of deleting them, so they are easy to bring back.
• Remember the AND semantics. Quick filters narrow; they do not replace query scope. For scope switching, use a query selector.
• Label in business language. "Only mine", "Overdue", "Active customers" — not "owner = currentUser".

Related Chapters

• Views — the surrounding view, layout zones, and the layout builder
• Properties — the properties quick filters target, including which are filterable
• Filter Operators — the authoritative operator set per property family
• Query Parameters — the runtime filter/share-state model quick filters ride on
• Expressions — for showCondition
• REST API — the same filter notation used by raw mode