A reusable filter builder UI component with AND/OR boolean connectors
npm install preact-filter-builderfilter-builder
A reusable Preact-based filter builder UI component with AND/OR boolean connectors.
This library provides a flexible filter builder interface that allows users to create complex filter expressions with boolean logic. Filters can be defined dynamically through a schema, making it adaptable to different use cases.
- Dynamic filter definitions via schema
- AND/OR boolean connectors
- Nested filter groups
- JSON Logic serialization/deserialization
- Import/export functionality
- Customizable styling via CSS variables
``bash`
npm install filter-builder
- @preact/signals: ^1.2.0htm
- : ^3.1.0preact
- : ^10.19.0
`javascript
import { FilterBuilder, useFilterState } from 'filter-builder';
import 'filter-builder/styles/filter-builder.css';
const schema = [
{ name: 'count', relations: ['<', '<=', '>', '>='], valueType: 'int' },
{ name: 'ratio', relations: ['<', '<=', '>', '>=', '==', '!='], valueType: 'float' },
{ name: 'status', relations: ['==', '!='], valueType: 'string', options: ['active', 'inactive', 'pending'] },
{ name: 'enabled', relations: ['==', '!='], valueType: 'boolean' }
];
function App() {
const store = useFilterState(schema);
return html
<${FilterBuilder}
schema=${schema}
store=${store}
onAddFilter=${(groupId) => { / handle add / }}
onUpdateFilter=${(filterId, updates) => { / handle update / }}
onRemoveFilter=${(filterId) => { / handle remove / }}
/>
;`
}
Each filter in the schema has:
- name: The filter type identifierrelations
- : Array of allowed comparison operators (<, <=, >, >=, ==, !=)valueType
- : The type of value ('int', 'float', 'string', or 'boolean')options
- (optional): For 'string' types, an array of allowed values. If provided, a dropdown will be rendered instead of a text input. Can be an array of strings or objects with {value, label} format.
A demo page is included that shows the filter builder in action with a table of job positions.
To create a static bundled demo that works without a web server:
`bash`
npm install
npm run build
This will create a dist-demo directory with a single, self-contained index.html file. All JavaScript, CSS, and assets are inlined into this one file, so no web server is required. You can:
- Double-click dist-demo/index.html to open it in your browserfile://
- Or open it via the protocol (e.g., file:///path/to/dist-demo/index.html)
The demo source files are located in the demo/ directory (demo/index.html and demo/demo.js).
Note: The development version in the demo/ directory requires a web server (it uses ES modules that need to be served over HTTP). The built version above does not need a server.
To run the development demo:
1. Start a local web server from the project root:
`bash`
# Using Python 3
python3 -m http.server 8000
# Or using Node.js (if you have http-server installed)
npx http-server -p 8000
2. Open your browser and navigate to:
``
http://localhost:8000/demo/
The demo includes:
- A table of job positions with columns for years of experience, education, location, salary, and remote work options
- A filter builder that allows you to filter positions by:
- yearsExperience (integer) - numeric comparisonssalary
- (integer) - numeric comparisonseducation
- (string with dropdown) - equality/inequality with predefined optionslocation
- (string with dropdown) - equality/inequality with predefined optionsremote` (boolean) - true/false comparisons
-
- Real-time filtering as you create and modify filters
- Support for complex boolean logic with AND/OR connectors
MIT