Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@vojtechportes/react-query-builder

Package Overview
Dependencies
Maintainers
1
Versions
26
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@vojtechportes/react-query-builder

Simple, highly configurable query builder for react

  • 0.4.4
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
375
increased by63.04%
Maintainers
1
Weekly downloads
 
Created
Source

:information_source: RFC 1.x.x

Please note that right now I am planning to start working on version 1.x.x. It will involve lot of refactoring, new features and some breaking changes. I will try to introduce ways how to keep things backwards compatible though.

If you are interested, check https://github.com/vojtechportes/react-query-builder/issues/37 for RFC and let me know what you think and what new features you would welcome.


React Query Builder

Simple, highly configurable query builder
for React written in TypeSript

npm version License: MIT Travis CI Status Coverage Status DeepScan grade




Installation

npm install @vojtechportes/react-query-builder

or

yarn add @vojtechportes/react-query-builder

Demo

with examples of field definition and custom components...
...or check source code on GitHub

React Query Builder

Usage

import React from 'react';
import {
  Builder,
  BuilderFieldProps,
  BuilderComponentsProps,
} from 'react-query-builder';

const fields: BuilderFieldProps[] = [
  // Fields configuration
];

const data: any = [
  // Initial query tree
];

const components: BuilderComponentsProps = {
  // Custom components configuration
};

const MyBuilder: React.FC = () => (
  <Builder
    readOnly={false}
    fields={fields}
    data={data}
    components={components}
    onChange={data => console.log(data)}
  />
);

Configuration

Since React Query Builder is highly configurable, you can define look of the Query Builder, you can define and use your own components, set whether the Builder should be readOnly or not and of course, you will need to set up fields Query Builder will be using.

Lets start with fields...

import { BuilderFieldProps } from 'react-query-builder';

const fields: BuilderFieldProps[] = [
    {
        field: 'STATE',
        label: 'State',
        type: 'LIST',
        operators: ['EQUAL', 'NOT_EQUAL'],
        value: [
            { value: 'CZ', label: 'Czech Republic' },
            { value: 'SK', label: 'Slovakia' },
            { value: 'PL', label: 'Poland' },
        ],
    },
    {
        field: 'IS_IN_EU',
        label: 'Is in EU',
        type: 'BOOLEAN'
    }
];

As you can see, there are few things you can define. field, label, type, operators and value.

Field

Field is a key and needs to be unique, since it is used to reference field in query tree as you will see further down in documentation.

Label

Label is pretty obvious, so lets skip to type.

Type

Type can be any of following constants:

BOOLEAN
TEXT
DATE
NUMBER
STATEMENT
LIST
MULTI_LIST
GROUP (*)

* GROUP type is not intended to be used in field props definition but only in data object.

Operators

Operator can be array of following constants

LARGER
SMALLER
LARGER_EQUAL
SMALLER_EQUAL
EQUAL
NOT_EQUAL
ALL_IN
ANY_IN
NOT_IN
BETWEEN
NOT_BETWEEN
LIKE
NOT_LIKE
Value

Value can be either string (STATEMENT) or array of objects with value and label keys (LIST, MULTI_LIST). Values for other types are empty by default.

Data

Data can be either empty array or array of rules and groups.

[
    {
        "type": "GROUP",
        "value": "AND",
        "isNegated": false,
        "children": [
            {
                "field": "IS_IN_EU", // <- Type here is refering to field property in fields configuration
                "value": false
            }
        ]
    }
]

Components

Components is set of components you can use to customize React Query Builder. You can either just style them using styled-components or use your own components as long as they follow typings of original components.

You can customize following componetns

Select
SelectMulti
Switch
Input
Remove
Add
Component
Group
GroupHeaderOption

via config object

const components: BuilderComponentsProps = {
  form: {
    Select: MyCustomSelect,
    SelectMulti: MyCustomSelectMulti,
    Switch: MyCustomSwitch,
    Input: MyCustomInput,
  },
  Remove: MyCustomRemove,
  Add: MyCustomAdd,
  Component: MyCustomComponent,
  Group: MyCustomGroup,
  GroupHeaderOption: MyCustomHeaderOption,
};

onChange

onChange property is allowing you to retrieve query tree after every change that occures in React Query Builder.


Localization

To either use custom strings or localize ReactBuilder, you can use strings property on Builder component.

You can work with object of following format:

const strings: Strings = {
  "group": {
    "not": "Not",
    "or": "Or",
    "and": "And",
    "addRule": "Add Rule",
    "addGroup": "Add Group",
    "delete": "Delete"
  },
  "components": {
    "delete": "Delete"
  },
  "form": {
    "selectYourValue": "Select your value"
  },
  "operators": {
    "LARGER": "Larger",
    "SMALLER": "Smaller",
    "LARGER_EQUAL": "Larger or equal",
    "SMALLER_EQUAL": "Smaller or equal",
    "EQUAL": "Equal",
    "NOT_EQUAL": "Not equal",
    "ALL_IN": "All in",
    "ANY_IN": "Any in",
    "NOT_IN": "Not in",
    "BETWEEN": "Between",
    "NOT_BETWEEN": "Not between"
  }
};

It is not required to translate all the strings. Strings that are not specified by you will be loaded from default strings.

To work with multiple locales, you can use for example amazing i18next framework.

import React from 'react';
import { Builder, Strings } from '@vojtechportes/react-query-builder';
import { Trans, useTranslation } from 'react-i18next';

export const QueryBuiler:React.FC = () => {
  useTranslation('query-builder')

  const strings: Strings = {
    operators: {
      LARGER: <Trans ns="query-builder" i18nKey="larger" />,
      SMALLER: <Trans ns="query-builder" i18nKey="smaller" />
      /* And so on */
    }
  };

  return (
    <Builder
      strings={strings}
      fields={fields}
      data={[]}
      onChange={(data: any) => console.log(data)} 
      />
  );
};

#Feature development

Please check https://github.com/vojtechportes/react-query-builder/issues/37

Keywords

FAQs

Package last updated on 11 Feb 2021

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc