Getting Started

Migration to 2.0

React Query Builder 2.0 replaces the library's runtime styled-components implementation with an explicit package stylesheet and inherited CSS custom properties. Query data and component APIs remain compatible unless noted below.

Import the stylesheet

Import the stylesheet once in the client entry for every application that renders built-in components. Server-rendered applications should include the same import in the client and server build graph so the bundler emits one shared CSS asset.

Adapter styles remain owned by their host packages. Load host-library styles before the React Query Builder stylesheet when the adapter documentation requires them.

Application entry

import '@vojtechportes/react-query-builder/styles.css';

Customize CSS tokens

Set inherited --query-builder-* variables on an application wrapper for a shared theme or pass them through one Builder.style prop for a local override.

Wrapper tokens

.customer-filter {
  --query-builder-color-primary-default: #3157d5;
  --query-builder-group-padding: 0.75rem;
  --query-builder-radius-md: 0.5rem;
  --query-builder-shadow-group: 0 0.25rem 1rem rgb(0 0 0 / 12%);
}

Token values are resolved from lowest to highest priority:

Defaults generated into the package stylesheet.
Custom properties inherited from application CSS.
Color values supplied by the legacy ThemeProvider.
Custom properties passed through the Builder style prop.

Stable styling hooks

CSS Module class names are private build output. Use documented root classes, data attributes, component overrides, and CSS custom properties instead of generated hashes. See Theming for the complete token reference.

ThemeProvider is legacy

ThemeProvider, colors, and their public color types remain available for the 2.0 compatibility cycle. New integrations should use CSS custom properties. Existing provider integrations can migrate incrementally without an immediate API change. Only supplied legacy color values become inline custom properties. Omitted values continue to inherit from application CSS or use the stylesheet defaults.

OptionContainer remains polymorphic

The public OptionContainer keeps its as prop. Intrinsic and custom React elements keep their compatible props and forwarded refs, so existing polymorphic uses require no migration.

Versioned documentation

Version 2 Documentation and API reference.
Version 1 Documentation and API reference.

Use the v1 pages when maintaining a 1.33.1 application. New integrations and migrations should follow the v2 documentation.