Rule Builder React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Rule Builder is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import RuleBuilder from @/components/ui/rule-builder.

import { useState } from "react"
import { FileWarning, Mail, Tag } from "lucide-react"
import {
  RuleBuilder,
  describeRule,
  type RuleActionDef,
  type RuleTriggerDef,
  type RuleValue,
} from "@/components/ui/rule-builder"

const days = (count: number) => (count === 1 ? "1 day" : `${count} days`)

const triggers: RuleTriggerDef[] = [
  {
    type: "invoice-overdue",
    label: "Invoice overdue",
    icon: <FileWarning />,
    params: [{ id: "days", label: "After", type: "days", required: true, defaultValue: 30 }],
    fields: [
      { id: "amount", label: "Amount", type: "currency" },
      {
        id: "city",
        label: "City",
        type: "select",
        options: [
          { value: "Austin", label: "Austin" },
          { value: "Portland", label: "Portland" },
        ],
      },
    ],
    summary: (params) => `an invoice is **${days(Number(params.days))}** overdue`,
  },
]

const actions: RuleActionDef[] = [
  {
    type: "send-email",
    label: "Send email",
    icon: <Mail />,
    tone: "info",
    params: [
      {
        id: "template",
        label: "Template",
        type: "select",
        required: true,
        options: [{ value: "final-notice", label: "Final notice" }],
      },
    ],
    summary: () => "send the **“Final notice”** email to the client",
  },
  {
    type: "add-tag",
    label: "Add tag",
    icon: <Tag />,
    params: [{ id: "tag", label: "Tag", type: "text", required: true }],
    summary: (params) => `add the **${params.tag}** tag`,
  },
]

export function OverdueRule({
  initial,
  onSave,
}: {
  initial: RuleValue
  onSave: (rule: RuleValue, sentence: string) => void
}) {
  const [rule, setRule] = useState(initial)
  return (
    <RuleBuilder
      title="Final notice after 30 days"
      triggers={triggers}
      actionTypes={actions}
      value={rule}
      onValueChange={(next) => {
        setRule(next)
        onSave(next, describeRule(next, { triggers, actions }))
      }}
      onTest={async () => ({ matched: true, message: "Invoice #2026-0371 would get the final notice." })}
      labels={{ test: "Dry run", enabled: "On" }}
    />
  )
}

Props

• triggers*
  RuleTriggerDef[]

  The trigger catalog: { type, label, description?, icon?, group?, params?, fields?, summary? }. fields are the lib/filters fields the conditions can test (an invoice, a deal, a lead); summary(params) says the trigger in a sentence with values wrapped in **, like "an invoice is **30 days** overdue".

• actionTypes*
  RuleActionDef[]

  The action catalog: { type, label, description?, icon?, group?, tone?, params?, summary?, multiple? }. tone colors the icon tile; multiple: false allows the action once per rule, so it leaves the picker once used. Named actionTypes because actions is the value's list.

• titledefault ""
  ReactNode

  The rule's name in the header. It also names the switch, so a screen reader hears which rule turns on or off.

• value
  RuleValue

  The rule: { trigger: { type, params } | null, conditions: FilterGroup, actions: { id, type, params }[] }. conditions is the lib/filters group a saved view or filter-builder uses, root level only.

• defaultValue
  RuleValue

  The starting rule while uncontrolled; an empty rule (createRule()) when left out.

• onValueChange
  (value: RuleValue) => void

  Every applied change: an editor's Apply, a picked trigger, an added, duplicated, moved or removed step, the all / any switch. Drafts in an open editor never reach it.

• enabled
  boolean

  Controlled state of the header switch; pair it with onEnabledChange.

• defaultEnableddefault true
  boolean

  Whether the rule starts switched on. A switched off rule's cards dim to 60%.

• onEnabledChange
  (enabled: boolean) => void

  Fires when the header switch flips.

• readOnlydefault false
  boolean

  Summaries only: cards without editors, menus, grips or add buttons, and a switch that shows its state. Test still works.

• disableddefault false
  boolean

  Dims and locks everything: cards, menus, grips, add buttons, the switch and Test.

• onTest
  (value: RuleValue) => Promise<RuleTestResult>

  Shows the Test button. While the promise runs the button spins; the result ({ matched, message?, steps?: { actionId, ok, message? }[] }) appears under the summary with each action's outcome, and any edit clears it. A rejection shows labels.testFailed.

• allowOrdefault true
  boolean

  Lets the conditions match any instead of all: an all / any switch appears once there are two conditions. Off, conditions always join with and.

• maxActionsdefault 0
  number

  The most actions a rule may have; the add button hides at the limit. A value below the current count removes nothing. 0 means no limit.

• validatedefault "touched"
  "always" | "touched" | "never"

  When issues show on the cards (a red ring and a line saying what is missing): always, only after a step was edited once, or never (the app validates with validateRule).

• responsivedefault true
  boolean

  Below 768px the step editors, the trigger, field and action pickers and the card menus open as bottom sheets. Off, phones get the desktop editor under the card.

• showSummarydefault true
  boolean

  The dashed box that reads the whole rule as one sentence, values in bold.

• summaryPositiondefault "bottom"
  "top" | "bottom"

  Where the sentence sits: under the header or after the actions.

• sizedefault "md"
  "sm" | "md"

  Step cards 48 / 56px tall with 28 / 32px icon tiles, and sm / md fields in the desktop editors. On touch screens every card is at least 56px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Colors the section pills (When, If, Then), the rails between them, the action numbers and the switch. neutral uses foreground tints.

• colordefault ""
  string

  Any CSS color; replaces the tone for the pills, rails, numbers and switch. Leave empty to use the tone.

• currencydefault "USD"
  string

  ISO 4217 code for currency params and currency fields that do not set their own; amounts read like $5,000.

• localedefault ""
  string

  Formats numbers, money and dates in cards, fields and the sentence (en-US: $5,000). Empty uses the UIProvider's locale, then the browser's.

• labels
  RuleBuilderLabelsInput

  Every visible and spoken string, merged over DEFAULT_RULE_BUILDER_LABELS: when, if, then, chooseTrigger, chooseAction, chooseField, addCondition, addAction, all, any, matchAll, matchAny, match, noConditions, noActions, edit, duplicate, moveUp, moveDown, remove, change, more, apply, cancel, required, back, enabled, test, testing, matched, notMatched, testFailed, stepOk, stepFailed, dismiss, summary, summaryEmpty, trigger, condition, field, operator, value, from, to, choose, search, noResults, daysUnit, days(count, formatted), unknownTrigger, unknownAction, unknownField, fieldUnavailable, incomplete, missing(label), sentence { when, if, then, and, or, comma, nothing }, operators (per filter operator), dragHandle(label), dragInstructions and announce { added, removed, moved, pickedUp, cancelled, pruned }.

• classNames
  Partial<Record<"header" | "title" | "enabled" | "test" | "section" | "sectionLabel" | "rail" | "steps" | "step" | "stepButton" | "stepIcon" | "stepNumber" | "stepSummary" | "stepIssue" | "stepMenu" | "stepHandle" | "joiner" | "editor" | "editorFooter" | "combinator" | "add" | "empty" | "summary" | "testResult" | "sheet", string>>

  Extra classes for the inner parts; step is the card, stepButton the stretched button that opens its editor, sheet the phone editor.

• className
  string

  Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone-soft:...].

Parts

FAQ

More React AI components