Structured-Filter-React is a React component, written in TypeScript, for building structured search/filter queries.
With it you can build structured search conditions like Firstname starts with 'A' and Birthday after 1/1/1990 and Category in (Family, Friends)...
Check out the Demo.
Light theme:
Dark theme:
This is the React re-write of Structured-Filter, the original jQuery UI widget.
npm install structured-filter-reactreact and react-dom (18 or 19) are peer dependencies and must already be installed in your project.
import Filter from "structured-filter-react";
import "structured-filter-react/dist/index.css";
const fields = [
{ id: "lastname", type: "text", label: "Lastname" },
{ id: "firstname", type: "text", label: "Firstname" },
{ id: "active", type: "boolean", label: "Is active" },
{ id: "age", type: "number", label: "Age" },
{ id: "bday", type: "date", label: "Birthday" },
{
id: "category", type: "list", label: "Category",
list: [
{ id: "1", text: "Family" },
{ id: "2", text: "Friends" },
{ id: "3", text: "Business" },
{ id: "4", text: "Acquaintances" },
{ id: "5", text: "Other" },
],
},
];
const App = () => <Filter fields={fields} />;Check the Demo for a full example, including reading the current conditions back out via onChange.
Each field must have an id, a type, and a label.
id- unique identifier for the field.label- displayed field name.type- one of:text,number,boolean,date,time,list.
Fields of type list must also have a list property: an array of { id, text } options.
The filter's value is an array of conditions, each shaped as:
{ field: string, operator: string, value: string | string[] | null }The available operators depend on the field's type:
| Type | Operators |
|---|---|
text |
equals (eq), not equal (ne), starts with (sw), contains (ct), doesn't contain (nct), finishes with (fw), is empty (null), is not empty (nn) |
number |
= (eq), != (ne), > (gt), < (lt), is empty (null), is not empty (nn) |
boolean |
equals (eq), is empty (null), is not empty (nn) |
date |
on/not on (eq/ne), after (gt), before (lt), between/not between (bw/nbw), is empty (null), is not empty (nn) |
time |
at/not at (eq/ne), after (gt), before (lt), between/not between (bw/nbw), is empty (null), is not empty (nn) |
list |
any of (in), is empty (null), is not empty (nn) |
Note:
between/not betweenare exposed in the operator dropdown fordate/timefields, but the value editor currently only captures a single value — a second "to" input isn't implemented yet.
| Prop | Type | Required | Description |
|---|---|---|---|
fields |
Field[] |
yes | The list of fields available to build conditions from. |
onChange |
(conditions: Condition[]) => void |
no | Called whenever the list of conditions changes. |
The package exports its TypeScript types alongside the component:
import type { Field, FieldType, ListOption, Condition, ConditionValue } from "structured-filter-react";npm install # install dependencies
npm run demo # run the demo app at http://localhost:3001
npm run build # build the library to dist/
npm run typecheck # type-check the projectStructured-Filter-React is released under the MIT license.
Encourage this project by becoming a sponsor.
Copyright (c) 2026 Olivier Giulieri.