Skip to content

Query builder for React applications based on Material UI v4.

License

Notifications You must be signed in to change notification settings

tiagofernandez/mui-querybuilder

Repository files navigation

MUI-QueryBuilder

Query builder for React applications based on Material-UI. Check the Storybook!

npm package npm downloads

Installation

MUI-QueryBuilder is available as an npm package.

yarn add --exact mui-querybuilder \
    @date-io/[email protected] \
    @date-io/[email protected] \
    @material-ui/core \
    @material-ui/icons \
    @material-ui/lab \
    @material-ui/pickers \
    date-fns \
    prop-types

Usage

Here is a quick example to get you started:

import MuiQueryBuilder from "mui-querybuilder";

import React, { useState } from "react";
import ReactDOM from "react-dom";

const filters = [
    {
        label: "Article",
        options: [
            {
                label: "Title",
                value: "title",
                type: "text",
            },
            {
                label: "URL",
                value: "url",
                type: "text",
            },
        ],
    },
];

function App() {
    const [query, setQuery] = useState({
        combinator: "and",
        rules: [
            {
                field: "title",
                operator: "contains",
                value: "France",
            },
        ],
    });
    return (
        <MuiQueryBuilder
            filters={filters}
            query={query}
            onChange={(query, valid) => {
                setQuery(query);
            }}
        />
    );
}

ReactDOM.render(<App />, document.querySelector('#app'));

Examples

Check out some examples in here!

API

Types

  • date: renders a date picker, date only.
  • integer: renders a text field that only accepts numbers.
  • number: renders a text field that only accepts fractional numbers.
  • multiselect: renders an autocomplete input for multiple items.
  • radio: renders radio buttons with true and false values.
  • select: renders an autocomplete input for a single item.
  • switch: renders an on/off switch input.
  • text: renders a text field.

Filters

The filters object is a list of grouped objects with label (string) and options (list) properties. Each option is an object with label (string), value (string), and type (string). The label can be anything, but the value must be an unique key, used by each field in a ruleset. In case an option's type is select or multiselect, it will require a nested options (list) property with label & value items.

Operators

In order to relate operators to their corresponding types, we rely on this data structure. Each operator must have a label (string), unique value (string), and the types (list) it supports.

Query

The query object is a recursive data structure composed of combinator (string) and rules (list) properties. Each rule is an object with field (string), operator (string), and value (anything, depending on the field's type). In case the rule contains a combinator property, it's considered a nested group.

Properties

Property Type Default Description
customOperators object {} Additional operators to be used by the query builder.
debug bool false Dev mode helper that renders the generated query directly in the screen.
filters array [] The filters the query builder framework will rely to create rules.
maxLevels number 1 The max nesting level, with 0 meaning no nesting at all.
operators array [...operators] The operators to be used, in case you want to change or translate the default ones.
onChange func null Function (query: object, valid: bool) => void with the current query and its validity (true if all rules have values).
query object { combinator: "and", rules: [{ field: null, operator: null, value: null }] } The initial query to be rendered.
sortFilters bool true Option to disable sorting filters within their groups.

Utility functions

import MuiQueryBuilder from "mui-querybuilder";

// Formats a query by deleting IDs from all nodes.
const formattedQuery = MuiQueryBuilder.formatQuery(query);

// Verifies if a query is valid, i.e. all rules and nested groups are filled.
const valid = MuiQueryBuilder.isQueryValid(query);

License

This project is licensed under the terms of the MIT license.

About

Query builder for React applications based on Material UI v4.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published