@databit/filters

A powerful, framework-agnostic input filter component with syntax highlighting, code completion, and type validation. Build complex filter expressions with an intuitive syntax.

npm: @databit/filters

Don't worry, not real data :) Data generated by https://www.mockaroo.com/

Features

• 🎨 Syntax Highlighting - Visual feedback for filter expressions
• 💡 Code Completion - Smart suggestions for variables and their values
• ✅ Type Validation - Real-time error detection for syntax and type mismatches
• 🔧 Highly Configurable - Custom variables, types, completion functions and styling
• 🚀 Framework Support - Available for React, Vue, Solid, Svelte, and Angular

Installation

npm install @databit/filters

or

pnpm install @databit/filters

Add styles to either JS or CSS:

In CSS:

@import "@databit/filters/index.css";

or if you want to import it through JS:

import "@databit/filters/index.css";

Framework-Specific Packages

For better integration with your favorite framework, use one of the framework-specific packages:

• React: @databit/filters-react
• Vue: @databit/filters-vue
• Solid: @databit/filters-solid
• Svelte: @databit/filters-svelte
• Angular: @databit/filters-angular

Syntax

The filter supports nested boolean expressions:

(gender = "Male" and age < 30) or (gender = "Female" and age < 20)

• Comparison: =, !=, <, >, <=, >=
• Logical: and, or
• Grouping: (, )

API Reference

FiltersProps

| Property | Type | Required | Description | |----------|------|----------|-------------| | value | string | No | The current filter expression value | | placeholder | string | No | Placeholder text shown when input is empty | | errorMessage | string | No | Custom error message to display under the input | | onValueChange | (params: FiltersOnValueChangeParams) => void | No | Callback fired when the filter value changes. value in params is always present, output will be null when the filter is invalid | | variableCompletionsFn | (search: string) => string[] | No | Function to provide variable name suggestions based on search input | | valueCompletionsFn | (search: string, variable: string) => string[] | No | Function to provide value suggestions for a specific variable | | variables | Record<string, ValueType> | No | Object mapping variable names to their types (e.g., integer, float, string, boolean) |

FiltersOnValueChangeParams

| Property | Type | Description | |----------|------|-------------| | value | string | The raw filter expression string | | output | FiltersOutput \| null | Parsed filter output object, or null if invalid |

ValueType

The ValueType object represents the data type of a variable. Supported types include:

• Integer via integer()
• Float via float()
• String via string()
• Boolean via boolean()

Usage

Basic Setup

import { createFilters } from "@databit/filters";

// grab an Element from the DOM
// <div id="root"></div> exists somewhere
// in HTML
const rootEl = document.querySelector("#root");

// run the filters input
const filters = createFilters(rootEl, {
  placeholder: 'e.g. (x = "hello") and y < 9'
});

Configuring Variables

import {
  createFilters,
  integer,
  string,
} from "@databit/filters";

const filters = createFilters(rootEl, {
  variables: {
    "x": string(),
    "y": integer(),
  },
});

Handling Value Changes

const filters = createFilters(rootEl, {
  onValueChange: ({ value, output}) => {
    if (output) {
      // output exists so filter is valid
    }
  },
});

Custom Completions

const variables = {
  "x": string(),
  "y": integer(),
};

// ["x", "y"]
const variableList = Object.keys(variables);

const filters = createFilters(rootEl, {
  variables,
  variableCompletionsFn: (search) => {
    return variableList.filter((variable) => {
      return variables.includes(search)
    });
  },
  valueCompletionsFn: (search, variable) => {
    // will always show those 3 values
    // when autocompleting values
    return ['one', 'two', 'joe']
  },
});

Updating Props

const filters = createFilters(rootEl);

// you can also update more than one prop with
// filters.updateProps({ ...props });
filters.updateProp('value', 'y = 3');

Cleanup

const filters = createFilters(rootEl, {
  placeholder: 'e.g. (x = "hello") and y < 9'
});

// ... do something ...

filters.dispose();

Styling

CSS Properties

| Property | Description | |----------|-------------| |--dbi-text-font-size|Font size of textbox, must be in px| |--dbi-text-line-height|Line height of textbox, must be in px| |--dbi-text-font-family|Font family of textbox| |--dbi-border|Border of whole input e.g. 1px solid #ccc| |--dbi-border-radius|Border radius of whole input| |--dbi-margin|Margin of whole input| |--dbi-padding|Padding of whole input| |--dbi-text-caret-color|Color of the caret inside of textbox| |--dbi-background|Background of the input| |--dbi-text-selection-background-color|Selection color of the textbox |--dbi-text-selection-color|Selection color of the font of the textbox| |--dbi-text-color|Default color of the text in textbox| |--dbi-text-placeholder-color`|Color of the placeholder|

CSS Classes

| Class | Description | |----------|-------------| |dbf-operator|Operators e.g. =, >, etc.| |dbf-logic-operator|Logic operator and or| |dbf-value|Values e.g. "string" or 9| |dbf-paren|Parentheses (``)| |dbf-paren.dbf-level-[X]| Nested parentheses, for example in ((x = 9)) the inner parentheses would be dbf-paren.dbf-level-1, currently there are levels 1 to 4| |dbf-error|Error| |dbf-error-message|Error message on the bottom of input |dbi-completion-box |The completion box| |dbi-message-box`|The message box, for example the ones with hovered errors or variable type info|

Error Handling

The component automatically detects and displays errors:

• Syntax Errors - Invalid filter expression syntax
• Type Errors - Type mismatches (e.g., comparing strings to integers)

Errors are displayed by hovering the underlined part of input.

onValueChange({ value, output }) output parameter is null when there is an error in the filter query, be it syntax error or other, like unknown variables.

License

Databit Community License

Copyright (c) 2025 Databit

You may use this software freely for any purpose. You must not remove or hide the "Databit Filter" watermark link. This software is provided as-is with no guarantees or warranties of any kind.

Support

For issues and feature requests, please use the GitHub issue tracker.