Theming

Stylesheet and tokens

• @vojtechportes/react-query-builder/styles.css Import this public stylesheet exactly once in the application entrypoint that renders v2 builders.
• @vojtechportes/react-query-builder/dark-mode.variables.css Optional dark palette for built-in components. Import it after styles.css before using colorScheme="dark".
• --query-builder-* Public inherited variables for colors, spacing, padding, gaps, radii, shadows, control sizing, typography, editor sizing, drop zones, motion, and popover layering.
• IBuilderStyle Typed React.CSSProperties extension containing every public variable accepted by Builder.style.
• Override boundaries Declare variables globally, on an app-owned wrapper, or on one Builder through its style prop.
• Stable selectors Use an app-owned Builder.className or [data-query-builder="root"]. Generated CSS Module classes such as rqb_[local]_[hash] are private and can change between releases.

Legacy ThemeProvider

export type ThemeColorOverrides = {
  [Key in keyof IColors]?: IColors[Key] extends string
    ? IColors[Key]
    : Partial<IColors[Key]>;
};

export interface IThemeProps<
  TColors extends ThemeColorOverrides = IColors,
> {
  colors?: TColors;
}

/** @deprecated Prefer public --query-builder-* CSS variables. */
export interface IThemeProviderProps
  extends IThemeProps<ThemeColorOverrides> {
  children?: React.ReactNode;
}

/** @deprecated Prefer public --query-builder-* CSS variables. */
export const ThemeProvider: React.FC<IThemeProviderProps>;

export interface IColorVariant {
  light: string;
  dark: string;
  default: string;
  contrastText: string;
}

export interface IGreyColorVariant {
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
}

export interface IColors {
  primary: IColorVariant;
  secondary: IColorVariant;
  grey: IGreyColorVariant;
  white: string;
}

export const colors: IColors;

Props and precedence

• colorScheme Optional 'light' | 'dark' palette boundary for one Builder. Leave it undefined to preserve inherited variables.
• colors Optional deep partial color overrides. Only provided leaves become CSS variables; omitted leaves continue to inherit from consumer CSS.
• children Optional React subtree that receives context without an added DOM node.
• Nested providers The nearest provider replaces the outer context value. Missing legacy values resolve from the exported colors defaults instead of the outer provider.
• Precedence Base defaults, inherited variables, explicit light/dark scheme variables, consumer root classes, legacy provider colors, then Builder.style values.
• Monaco note The packaged Monaco light and dark themes map SQL tokens to the same query-builder palette roles as the built-in editor. An undefined colorScheme uses the packaged light theme. Monaco's standalone theme service is global, so the latest mounted packaged editor, or the editor whose scheme changes most recently, wins across all mounted editors. Synchronizing consumer CSS variable overrides or custom per-editor themes remains application-managed.
• Adapter note ThemeProvider affects the built-in default components. Packaged host-library adapters use their own theme systems.