Filter Builder

<loomi-filter-builder> — a structured filter editor for tables, reports, CRM lists, and server-side query workflows.

Typed fields, field-specific operators, and / or logic, and API-friendly { logic, rules } output.

Installation

npm install @loomidev/filter-builder

Import

import "@loomidev/filter-builder";

Basic Usage

Assign fields as a JavaScript property, then listen for apply events.

const builder = document.querySelector("loomi-filter-builder");

builder.fields = [
  { key: "name", label: "Name", type: "text" },
  {
    key: "status",
    label: "Status",
    type: "select",
    options: [
      { label: "Active", value: "Active" },
      { label: "Invited", value: "Invited" },
    ],
  },
];

builder.addEventListener("loomi-filter-apply", (event) => {
  console.log(event.detail.value);
});

<loomi-filter-builder apply-label="Apply filters"></loomi-filter-builder>

With Initial Rules

Seed the builder with an initial ruleset through a JavaScript property.

<loomi-filter-builder logic="and"></loomi-filter-builder>

builder.rules = [
  { id: "status-active", field: "status", operator: "equals", value: "Active" },
];

Field types & operators

Each fields entry’s type picks the value control it renders (a select for "select", a typed <input> otherwise) and the default operator list offered for that row — override per-field with field.operators.

type	Value control	Default operators
text	Text input	contains, equals, notEquals, startsWith, endsWith
number	Number input	equals, notEquals, gt, gte, lt, lte
date	Date input	equals, before, after
boolean	(none — operator alone is the value)	isTrue, isFalse
select	field.options dropdown	equals, notEquals

builder.fields = [
  { key: "revenue", label: "Revenue", type: "number", operators: ["gte", "lte"] },
];

Accessibility

• Each rule row exposes labelled field, operator, and value controls.
• Remove actions include an accessible name.

For the library-wide baseline, see Foundations — Accessibility.

Responsive behavior

• Each rule row collapses to a single column below 720px.

For the shared container and viewport rules, see Foundations — Responsive behavior.

Dark mode

For theme activation, token overrides, and contrast guidance, see Foundations — Dark mode.

Properties

Property	Type	Default	Notes
fields	FilterBuilderField[]	[]	JavaScript property. Drives the field picker, value control, and operator list per row.
rules	FilterBuilderRule[]	[]	JavaScript property. Each rule is { id, field, operator, value }.
logic	"and" | "or"	"and"	Reflected attribute. Combinator shown in the header toggle.
title	string	"Filters"	Heading text.
add-label	string	"Add filter"	Label for the add-rule button.
apply-label	string	"Apply filters"	Label for the apply button (only rendered when show-apply).
empty-label	string	"No filters added"	Shown in place of the rule list when rules is empty.
show-apply	boolean	true	Reflected attribute. Hides the apply button when false — use this for filters that should apply live via loomi-filter-change instead.

Events

Event	Detail
loomi-filter-change	{ value } — fires on every add/remove/edit of a rule or logic change.
loomi-filter-apply	{ value } — fires when the apply button is clicked.

Both detail shapes are { logic, rules } — the same object fields/rules describe.

Design Notes

• The value shape is intentionally API-friendly: { logic, rules }.
• Apps should translate the emitted rules into SQL, API query params, GraphQL variables, or table-local filters.
• Server-side tables should listen for loomi-filter-apply and refresh data from the backend.

Dependencies

• @loomidev/core