Structured-Filter-React

With it you can build structured search conditions like Firstname starts with 'A' and Birthday after 1/1/1990 and State in (CA, NY, FL)...

Installation

npm install structured-filter-react

react and react-dom (18 or 19) are peer dependencies and must already be installed in your project.

Usage

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.

Model

Fields

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.

Conditions

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 between are exposed in the operator dropdown for date/time fields, but the value editor currently only captures a single value — a second "to" input isn't implemented yet.

Props

<Filter>

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.

Types

The package exports its TypeScript types alongside the component:

import type { Field, FieldType, ListOption, Condition, ConditionValue } from "structured-filter-react";

Development

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 project

License

Structured-Filter-React is released under the MIT license.

React component for building structured search queries

Demo

Documentation