Data Table Filter
<zn-data-table-filter> | ZnDataTableFilter
An inline filter bar for data tables. Each active filter is a pill whose dropdown sets its value.
<zn-data-table-filter filters="[{"id":"title","name":"Title","operators":["eq"]},{"id":"author","name":"Author","operators":["eq","fuzzy"]},{"id":"genre","name":"Genre","options":{"action":"Action","comedy":"Comedy","drama":"Drama","fantasy":"Fantasy","horror":"Horror","mystery":"Mystery","romance":"Romance","thriller":"Thriller","sci-fi":"ScienceFiction"},"maxOptionsVisible":"3","operators":["eq","in"]},{"id":"rating","name":"Rating","type":"number","operators":["eq","gt","gte","lt","lte"]},{"id":"created","name":"Created","type":"date","operators":["eq","before","after"]}]"> </zn-data-table-filter>
Filters render inline rather than in a slideout. Each active filter is a pill showing its name, and its
value once set; the pill’s dropdown lists the filter’s options as checkable values, or a text
input for a filter that declares none. Each pill carries an X that drops that filter.
+ Add filter lists the filters that are not yet active, and Clear removes them
all.
A filter starts on its first declared operator. Declare more than one and the pill offers a
choice: a value editor gets a row of operator chips above it, an options menu lists the operators above its
values, and the pill then reads Age ≥ 18 rather than Age: 18. Switching operator
keeps the value — a date is re-encoded for the new comparator.
Declare in or nin to let a filter hold several values at once — the pill then
counts them, e.g. Role (2), and its dropdown stays open so you can pick more. Any other
operator holds a single value: the dropdown closes on select, and picking the same value again clears it.
Picking a filter from + Add filter opens its pill straight away, with a text field focused, so
naming a filter and giving it a value is one pass. A typed value is one value however many spaces it
contains; only a comma starts another.
default-filters takes a comma-separated list of filter ids to show a pill for up front. Inside
a zn-data-table the bar is hidden until the header’s filter toggle is clicked, and
activeCount reports how many filters currently hold a value.
<zn-data-table-filter default-filters="status" filters='[ {"id":"status","name":"Status","options":{"open":"Open","closed":"Closed"},"operators":["eq"]}, {"id":"tag","name":"Tag","options":{"bug":"Bug","chore":"Chore","feature":"Feature"},"operators":["in"]}, {"id":"owner","name":"Owner","operators":["contains"]} ]'> </zn-data-table-filter>
The component emits zn-filter-change and exposes the query on value, encoded
exactly as zn-query-builder encodes it — base64 of [{key, comparator, value}] — so
a backend built against the query builder needs no changes.
Setting value round-trips: assigning that same base64 string back — for example restoring it
from a shared URL via zn-data-table’s
sharable sync — rebuilds the active
pills, so the bar reopens in the state it was encoded in. Restoration needs the filters schema
present to resolve each key, and it stands down once any filter already holds a value, so a shared filter
still wins over an empty default-filters pill while a filter the user is mid-way through
setting is never clobbered.
One caveat: a restored date filter shows its raw encoded value on the pill (a timestamp, or a minutes-from-now offset) rather than a formatted date, because the human-readable label is not part of the encoded query. The filter still applies correctly; only the pill text differs until the value is re-picked.
Long Option Lists
An option list caps its height at 320px and scrolls inside the panel rather than running off the screen, with the scrollbar drawn rather than left to the platform’s overlay one. Past eight options the pill also gains a search field, merged into the top of the panel and pinned there, that narrows the list case-insensitively.
<zn-data-table-filter default-filters="category" filters='[ {"id":"category","name":"Category","operators":["eq","in"],"options":{ "how-to":"How To","linux":"Linux","beta":"Beta","router":"Router","tv":"TV","other":"Other", "mac":"Mac Hotspot Shield","general":"General","android":"Android Hotspot Shield", "educational":"Educational","windows":"Windows Hotspot Shield","ios":"iOS", "getting-started":"Getting Started","payments":"Payments & Subscriptions", "accounts":"Manage Account & Devices","troubleshoot":"Troubleshoot issues", "releases":"Release Notes","archived":"Archived Articles","internal":"Internal Information", "tutorials":"Tutorials"}} ]'> </zn-data-table-filter>
Typeahead
Inside a zn-data-table a text filter suggests values from the rows the table has already
loaded, matched case-insensitively against what has been typed, keyed on the column whose name matches the
filter’s id. Set suggestions yourself — {[filterId]: string[]} — to offer
something else.
Examples
Basic Text Filters
Create simple text-based filters with equality and fuzzy search operators.
<zn-data-table-filter filters="[{"id":"name","name":"Name","operators":["eq","fuzzy"]},{"id":"email","name":"Email","operators":["eq","fuzzy"]},{"id":"company","name":"Company","operators":["eq"]}]" name="text-filters"> </zn-data-table-filter>
Number Filters with Operators
Use number type filters with comparison operators like equal, greater than, less than. The pill’s editor
shows a chip per operator; >, ≥, < and ≤ keep
their symbols, and the rest read as words.
<zn-data-table-filter filters="[{"id":"age","name":"Age","type":"number","operators":["eq","gt","gte","lt","lte"]},{"id":"price","name":"Price","type":"number","operators":["eq","gt","lt"]},{"id":"quantity","name":"Quantity","type":"number","operators":["eq","gte","lte"]}]" name="number-filters"> </zn-data-table-filter>
Date Filters
Filter by dates with before, after, and equal operators. A date pill opens a calendar and
closes once a day is picked; a dateTime pill adds a time selector and stays open while it’s
set.
Values are encoded the way zn-query-builder encodes them, so
dateSubmitFormat picks the wire format: legacy (the default — seconds for
eq/neq, otherwise minutes from now, negated for before),
timestamp (milliseconds) or iso.
<zn-data-table-filter filters="[{"id":"created","name":"Created Date","type":"date","operators":["eq","before","after"]},{"id":"modified","name":"Modified Date","type":"date","operators":["before","after"]},{"id":"due_date","name":"Due Date","type":"dateTime","dateSubmitFormat":"iso","operators":["eq","before","after"]}]" name="date-filters"> </zn-data-table-filter>
Dropdown Options
Use predefined options for select-based filtering.
<zn-data-table-filter filters="[{"id":"status","name":"Status","options":{"open":"Open","in_progress":"In Progress","closed":"Closed"},"operators":["eq","in"]},{"id":"priority","name":"Priority","options":{"low":"Low","medium":"Medium","high":"High","critical":"Critical"},"operators":["eq","in"]}]" name="option-filters"> </zn-data-table-filter>
Limited Options Display
Control how many options are initially visible using maxOptionsVisible.
<zn-data-table-filter filters="[{"id":"category","name":"Category","options":{"cat1":"Category 1","cat2":"Category 2","cat3":"Category 3","cat4":"Category 4","cat5":"Category 5","cat6":"Category 6"},"maxOptionsVisible":3,"operators":["eq","in"]}]" name="limited-options"> </zn-data-table-filter>
Mixed Filter Types
Combine different field types in a single filter component.
<zn-data-table-filter filters="[{"id":"product","name":"Product Name","operators":["eq","fuzzy"]},{"id":"category","name":"Category","options":{"electronics":"Electronics","clothing":"Clothing","books":"Books"},"operators":["eq","in"]},{"id":"price","name":"Price","type":"number","operators":["eq","gt","lt"]},{"id":"in_stock","name":"In Stock","type":"boolean","operators":["eq"]}]" name="mixed-filters"> </zn-data-table-filter>
Employee Filter Example
A practical example for filtering employee data.
<zn-data-table-filter filters="[{"id":"employee_name","name":"Employee Name","operators":["eq","fuzzy"]},{"id":"department","name":"Department","options":{"engineering":"Engineering","sales":"Sales","marketing":"Marketing","hr":"Human Resources","finance":"Finance"},"operators":["eq","in"]},{"id":"hire_date","name":"Hire Date","type":"date","operators":["before","after"]},{"id":"salary","name":"Salary","type":"number","operators":["gt","lt"]}]" name="employee-filters"> </zn-data-table-filter>
E-commerce Filter Example
Filter products with various criteria.
<zn-data-table-filter filters="[{"id":"title","name":"Product Title","operators":["eq","fuzzy"]},{"id":"brand","name":"Brand","operators":["eq"]},{"id":"category","name":"Category","options":{"electronics":"Electronics","clothing":"Clothing","home":"Home & Garden","sports":"Sports","toys":"Toys"},"maxOptionsVisible":3,"operators":["eq","in"]},{"id":"price","name":"Price","type":"number","operators":["eq","gt","gte","lt","lte"]},{"id":"rating","name":"Rating","type":"number","operators":["gte"]},{"id":"release_date","name":"Release Date","type":"date","operators":["before","after"]}]" name="product-filters"> </zn-data-table-filter>
Content Library Filter
Filter media content like books, movies, or articles.
<zn-data-table-filter filters="[{"id":"title","name":"Title","operators":["eq","fuzzy"]},{"id":"author","name":"Author","operators":["eq","fuzzy"]},{"id":"genre","name":"Genre","options":{"action":"Action","comedy":"Comedy","drama":"Drama","fantasy":"Fantasy","horror":"Horror","mystery":"Mystery","romance":"Romance","thriller":"Thriller","sci-fi":"Science Fiction"},"maxOptionsVisible":3,"operators":["eq","in"]},{"id":"rating","name":"Rating","type":"number","operators":["eq","gt","gte","lt","lte"]},{"id":"published","name":"Published Date","type":"date","operators":["eq","before","after"]}]" name="content-filters"> </zn-data-table-filter>
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.132/dist/components/data-table-filter/data-table-filter.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.132/dist/components/data-table-filter/data-table-filter.js';
To import this component using a bundler:
import '@kubex/zinc/dist/components/data-table-filter/data-table-filter.js';
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
defaultFilters
default-filters
|
Filter keys to show a pill for before the user adds any. |
string
|
''
|
|
suggestions
|
Typeahead values per filter key. zn-data-table fills this from the rows it has loaded.
|
Record
|
{}
|
|
activeCount
|
Number of filters with a value set. |
number
|
- | |
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
zn-filter-change |
|
Emitted when the active filters change. Read the encoded query off value. |
- |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
clear() |
Removes every active filter. | - |
Learn more about methods.
Dependencies
This component automatically imports the following dependencies.
<zn-button><zn-datepicker><zn-dropdown><zn-example><zn-icon><zn-input><zn-menu><zn-menu-item><zn-slash-item><zn-slash-menu><zn-tooltip>