Filters, Sorting & Pagination
Controlling which records show, in what order, and how many at a time. Filtering and sorting can be configured in two places — on the data source (narrowing what's fetched) and on the component (letting users explore what's shown). The Filters block is the primary UI component for exposing filter, sort, search, and date controls to the app user.
Filtering in Two Places
| Where | What it does | Use when |
| On the data source | Narrows the data before it ever reaches the component — fewer records are fetched, reducing payload size and server load. | You always want a fixed subset (e.g. only active records, only this user's records). Use data source filters to limit what's possible, not just what's shown. |
| On the component | Filters data already in memory — fast, but all records still flow from the server. Table and List components have Default Filter, Initial Filter, and Default Sort settings. | Providing a user-facing interactive filter over data the component already loaded. Good for lightweight, exploratory filtering within a known small dataset. |
The Filters Block
The Filters block is a toolbar of filter controls that together publish one shared filter state. The block never queries data itself — it reads field metadata from your data sources, lets the user compose criteria, and exposes the result as block state. You bind that state into your data source's inputs to drive re-fetching.
Note: Arrives pre-configured with three controls: a full condition-builder filter, a date range filter (preset to last 30 days), and a search box. You can add, remove, or reorder controls via Standard Actions in the inspector.
Connecting the Filters Block to a Data Source
Select Data Sources: In the Filters block inspector under Data Sources, pick the data sources the toolbar should understand. The block reads each source's field metadata to populate the condition builder, field chips, and sort menu. It reads metadata only — it never triggers a fetch on its own.
Bind exposed state to the data source inputs: In the data source's Input configuration, bind its filter, sort, and search parameters to the Filters block's state:
The data source re-runs automatically: Because the data source's inputs are bound to the Filters block state, and the data source is set to Automatic, it re-fetches whenever the user changes any filter, sort, or search control. No event handler is needed.
Filters Block Properties
| Property | Key | Type | Default | Description |
| Data Sources | dataSourceIds | string[] | [] | The data sources whose field metadata drives the condition builder and sort menu. |
| Standard Actions | primaryActions | array | data filter + date filter + search | The list of filter controls in the toolbar. Each entry has a type from the 7 available types. |
| Remember applied changes | persistFilters | boolean | — | Keep the user's applied filter, sort, search, and date range when they leave and return to the page in the same browser tab. |
The 7 Filter Control Types
Each filter control is one "action" in the Standard Actions list. Add, remove, or reorder them freely — with limits noted below.
| Type | What it adds | Multiple per block? | State key |
| Data filter | Full condition builder — users compose AND/OR groups over any filterable field. | No — last one wins | state.filter |
| Date filter | Date or date range picker with optional named presets (Last 30 days, This month, etc.). | No — last one wins | state.dateTimeFilter |
| Sort | Sort menu over the data source's sortable fields. Button label shows the current sort. | No — last one wins | state.sort |
| Search | Keyword search box. Result is a plain string — the data source handles the matching. | No — last one wins | state.search |
| Quick filter | One-click chip carrying a pre-configured filter or date range. | Yes — every one renders | state.filter (same slice as data filter) |
| Field filter | A chip scoped to one field of the data source. | Yes — every one renders | state.filter (merged into combined filter) |
| AI filter | A prompt popover — the user describes the filter in plain language and the block applies it. | No — last one wins | state.filter |
Filters Block Exposed State
Every control in the toolbar publishes its result under the block's name. Bind these into data source inputs to drive re-querying.
| State key | Type | Description |
| {{ filters1.state.filter }} | object | The combined filter tree — the condition builder output plus all field chip conditions merged under one AND group. |
| {{ filters1.state.search }} | string | The search box text. Empty string after the user clears the box. |
| {{ filters1.state.sort }} | array | Sort entries, each a field plus ASC or DESC. |
| {{ filters1.state.dateRangePreset }} | string | The active named preset (e.g. last30days); empty when the range is custom or fixed. |
| {{ filters1.state.dateTimeFilter.iso.startTime }} | string | Range start as an ISO string. |
| {{ filters1.state.dateTimeFilter.iso.endTime }} | string | Range end as an ISO string. |
| {{ filters1.state.dateTimeFilter.epoch.startTime }} | number | Range start as epoch milliseconds. |
| {{ filters1.state.dateTimeFilter.epoch.endTime }} | number | Range end as epoch milliseconds. |
| {{ filters1.state.dateTimeFilter.epoch.previousStartTime }} | number | Start of the equal-length period immediately before the selected range (for period-over-period comparisons). |
Data Filter (Condition Builder)
The data filter control adds a Filter button that opens a full condition builder. Users compose AND/OR filter groups over any filterable field of the selected data sources.
Condition Operators by Field Type
| Field type | Operators available |
| Text | Contains, Does not contain, Contains case sensitive, Equals to, Does not equal, Starts with, Ends with, Matches regex, Is present, Is not present |
| Number | Less than, Less than or equal to, Greater than, Greater than or equal to, Equals to, Does not equal, Is present, Is not present |
| Date/time | Equals to, Before, Before or equal to, After, After or equal to, Between, Is present, Is not present |
| Boolean | Is, Is not, Is present, Is not present |
| Lookup | Is, Is not |
Data Filter Properties
| Property | Type | Default | Description |
| label | string | — | The button text. |
| valueSource | enum | custom | custom: author an initial filter in the inspector. mapped: bind the filter from data. |
| initialValue | filter config | — | Conditions applied on page load (when Source = Custom). |
| allowedFilterFields | string[] | — | When set, only these fields are offered in the builder. Restricts the entire Filters block, not just this control. |
Sort Control
The sort control adds a sort menu. The button label derives from the currently applied order — no configurable label. The exposed state is {{ filters1.state.sort }}: an array of entries, each with a field and ASC or DESC direction.
| Property | Type | Description |
| valueSource | enum | custom or mapped. Custom: set the initial order in the inspector. Mapped: bind from data. |
| initialValue | sort config | Field-and-direction entries applied on load. |
Search Control
The search control adds a keyword search box. The user's input is published as {{ filters1.state.search }} — a plain string. Bind it to the data source's search parameter. The data source handles the actual matching.
Note: On desktop the search box sits at the opposite end of the toolbar from the other controls. On mobile it moves above the other controls and stretches to full width.
Pagination
Data-bound components (Table, List) support two pagination modes, set on the component's Pagination property.
| Type | Behavior | Configuration |
| Page based | Numbered pages with a page size. Viewers move between pages with prev/next controls. Total records count can be shown. | Page Size Mode: Fixed (one size) or User Selectable (you provide options list and default). Initial Page, optional total-records count. |
| Scroll based | Loads more as the viewer scrolls. Appends new records below existing ones. The default for most list-style blocks. | Driven by the data source's infinite loading capability. No additional configuration needed on the component. |
Warning: A table inside another table's row won't accept an automatic data source. Use a manual data source triggered per row, or bind the inner table to the current row's data using the row context: {{ outer_table.context.currentRow.nestedItems }}.
Filters Block Methods
Callable programmatically from any event via the Control Block Method action or from a binding expression.
| Method | Parameters | What it does |
| Reset | fields: any of filter, sort, search (default: all three) | Clears the chosen slices of state. Resetting filter also clears the date range, quick-filter selections, and all field chips. |
| Set Value | filter, sort, search, dateTimeFilter, dateRangePreset | Applies given values programmatically. Invalid-shape keys are silently dropped; valid siblings still apply. |
Patterns
Pattern 1 — Filter a table with a Filters block
// 1. Drop a Filters block above the table. Select the table's data source. // 2. In the data source's Input configuration, bind: filter: {{ filters1.state.filter }} search: {{ filters1.state.search }} sortBy: {{ filters1.state.sort }} startTime: {{ filters1.state.dateTimeFilter.epoch.startTime }} endTime: {{ filters1.state.dateTimeFilter.epoch.endTime }} // The query re-runs automatically whenever the user changes any control.
Pattern 2 — One-click status views with Quick Filters
// Add three Quick Filter actions to the Filters block: // "Open" — data filter: status Equals "open", Apply by default: ON // "In Progress" — data filter: status Equals "in_progress" // "Closed" — data filter: status Equals "closed" // Users switch views with one click. Picking a chip replaces the previous chip's filter. // The page loads pre-filtered to "Open" because it's set as the default.
Pattern 3 — Persist filters across navigation
// In the Filters block inspector, enable "Remember applied changes". // Now a user who filters a list, opens a detail page, and returns // finds their filter, sort, and search still applied for the tab session. // Closing the tab clears persisted state.
Gotchas
| Gotcha | Details |
| Resetting filter clears more than conditions | The Reset method's filter option wipes the condition builder, the date range, active quick filters, and all field chips in one go. Sort and search reset independently. |
| Set Value silently drops invalid shapes | Each key passed to Set Value is shape-checked. A key that fails the check is ignored — the error is silent, so a bad binding can cause the control to seem unresponsive. |
| Only one data/date/sort/search/AI control per block | Adding a second of any of these in Standard Actions is silently ignored — the last one in the list wins. Quick filters and field filters can repeat freely. |
| On Filter Change fires on load for controls with initial values | A control with an initial value configured fires On Filter Change on page load, so a bound query may run twice (once bare, once filtered). Plan for the double run in analytics or pagination resets attached to this event. |
| Remembered state overrides initial values | With Remember applied changes on, a returning user's stored state is restored and every configured initial value — including quick filters marked Apply by default — is skipped for that visit. |
| Mapped values overwrite user changes when the binding changes | For a control with Source = Mapped, the bound value re-applies whenever it changes after load — replacing whatever the user had composed. Bind mapped values only when the binding, not the user, should own that slice of state. |
| No filter fields = disabled controls | If the Filters block has no Data Sources selected, or the selected sources yield no filterable fields, all filter controls are disabled in the builder. Always configure Data Sources first. |
Frequently Asked Questions
How do I set a default filter that loads pre-applied when the page opens?
On the data filter control, set Source to Custom and configure your conditions under Value. Those conditions are applied on page load before the first query runs. For quick-filter chips, enable Apply by default on the chip you want pre-selected. Both approaches fire the On Filter Change event on load, so a bound automatic data source re-fetches once with the initial filter applied.
The filters panel shows no fields to filter by. What's wrong?
The Filters block reads field metadata from the data sources you select under Data Sources in the inspector. If no sources are selected, or the selected sources have no filterable fields, the condition builder shows empty. Add the relevant data source to the block's Data Sources list. Note that the block reads metadata — selecting a source here does not trigger that source to run.
Can I filter and sort at the data source level instead of using the Filters block?
Yes — platform query data sources have built-in filter, sort, and paging configuration in the Query Builder. Use this when the filter is fixed (always the same criteria) and doesn't need to change based on user input. Use the Filters block when users need to interactively compose their own criteria. Both can be combined: a fixed data-source filter narrows the dataset, and the Filters block lets users explore within that narrowed set.
How do I reset all filters when the user navigates to the page?
Use the Filters block's Reset method in the page's On Load event, or in a button action. Call it without arguments to reset filter, sort, and search simultaneously: {{ filters1.reset() }}. To reset only specific slices — for example just the search without clearing filters — pass the specific field: {{ filters1.reset({ fields: ['search'] }) }}.
Why does On Filter Change fire twice on page load?
A filter control with a configured initial value fires On Filter Change when the initial value is applied on load — which is intentional so bound queries can use the initial filter. However, if the data source is also set to run on page load (or runs automatically when the block mounts), the query runs once bare and once with the filter, appearing as a double fetch. This is normal behavior. If you want only one run, set the data source's Run Behaviour to Manual with Run query on page load on — then the initial filter is applied before the single seed run fires.