Checkbox

An intelligent boolean input component built on MUI Checkbox. Supports standalone usage, seamless DashForm integration with automatic field binding, validation error gating, and reactive visibility. Perfect for terms acceptance, settings toggles, and multi-option selections.

Quick Start

Copy & Paste

import { Checkbox } from '@dashforge/ui';

<Checkbox label="Accept terms" name="acceptTerms" />

Examples

Common Checkbox patterns and configurations

Basic

Binary choice with label for user agreement

Accept terms

<Checkbox label="Accept terms" name="acceptTerms" />

Checked by Default

Pre-selected for opt-out patterns

Subscribe to newsletter

<Checkbox label="Subscribe to newsletter" name="subscribe" checked />

Disabled

Prevent interaction when read-only

Disabled option

<Checkbox label="Disabled option" name="disabled" disabled />

Disabled and Checked

Show locked state with pre-accepted value

Terms (pre-accepted)

<Checkbox 
  label="Terms (pre-accepted)" 
  name="preAccepted" 
  checked 
  disabled 
/>

Error State

Validation feedback for required acceptance

I agree to terms

<Checkbox
  label="I agree to terms"
  name="terms"
  error
  helperText="You must accept the terms"
/>

Without Label

Compact toggle without descriptive text

<Checkbox name="standalone" />

Dashforge Capabilities

Progressive adoption from controlled components to predictive forms

Checkbox is designed for progressive adoption. Use it as a simple controlled component, integrate it with React Hook Form, or leverage Dashforge-native predictive capabilities. Choose the level that fits your team's workflow.

Controlled

Available Now

Checkbox works as a standard React controlled component with familiar patterns. No proprietary lock-in required.

Standard checked and onChange props

No proprietary lock-in

Easy incremental adoption

<Checkbox
  checked={accepted}
  onChange={(e) => setAccepted(e.target.checked)}
  label="Accept terms"
/>

React Hook Form Ready

Integration-Friendly

Designed to integrate with React Hook Form workflows through DashForm. Compatible with existing form-library patterns.

Works through DashForm bridge

Validation and error handling supported

Fits existing RHF workflows

<DashForm>
  <Checkbox 
    name="acceptTerms"
    label="I accept the terms"
    rules={{ required: 'You must accept terms' }}
  />
</DashForm>

Reactive Visibility

Available Now

Checkbox can participate in engine-driven visibility rules through visibleWhen. Use it when a boolean choice depends on other form state.

Conditional rendering via visibleWhen

Engine evaluates the predicate

Useful for dependent boolean fields

<Checkbox
  name="agreeToMarketing"
  label="I agree to marketing emails"
  visibleWhen={(engine) => 
    engine.getNode('createAccount')?.value === true
  }
/>

Access Control (RBAC)

Control field visibility and interaction based on user permissions. Fields can be hidden, disabled, or readonly when users lack access.

Hide when unauthorized

<Checkbox
  name="acceptTerms"
  label="I accept the terms"
  access={{
    resource: 'user.terms',
    action: 'view',
    onUnauthorized: 'hide'
  }}
/>

Disable when cannot edit

<Checkbox
  name="isPublished"
  label="Publish to marketplace"
  access={{
    resource: 'content.publish',
    action: 'edit',
    onUnauthorized: 'disable'
  }}
/>

Readonly for view-only

<Checkbox
  name="isVerified"
  label="Email verified"
  access={{
    resource: 'user.verification',
    action: 'edit',
    onUnauthorized: 'readonly'
  }}
/>

Combined with visibleWhen

<Checkbox
  name="requiresApproval"
  label="Requires legal approval"
  visibleWhen={(e) => 
    e.getValue('isCommercial') === true
  }
  access={{
    resource: 'license.approval',
    action: 'edit',
    onUnauthorized: 'readonly'
  }}
/>

Note: When combining visibleWhen with RBAC, both conditions must be satisfied. The field shows only if UI logic returns true AND the user has required permissions.

Form Integration

Real-world scenarios with React Hook Form and dynamic visibility

Checkbox works in real form contexts, not just isolated demos. Try these live scenarios to experience DashForm integration and reactive visibility—both fully implemented and production-ready.

React Hook Form Integration

Try it: Check the boxes and submit the form

Checkbox integrates seamlessly with React Hook Form through DashForm. Components self-register, errors display automatically after interaction, and validation follows familiar RHF patterns. Try submitting without accepting terms to see validation in action.

Live Preview

import { DashForm } from '@dashforge/forms';
import { Checkbox } from '@dashforge/ui';

function RegistrationForm() {
  const handleSubmit = (data: FormData) => {
    console.log('Submitted:', data);
  };

  return (
    <DashForm
      defaultValues={{ acceptTerms: false, subscribe: false }}
      onSubmit={handleSubmit}
      mode="onBlur"
    >
      <Checkbox
        name="acceptTerms"
        label="I accept the terms and conditions"
        rules={{
          required: 'You must accept the terms to continue'
        }}
      />
      <Checkbox
        name="subscribe"
        label="Subscribe to newsletter (optional)"
      />
      <button type="submit">Submit Registration</button>
    </DashForm>
  );
}

// Checkbox automatically:
// - Registers with React Hook Form
// - Syncs checked value from form state
// - Displays validation errors when touched
// - Tracks touched state on blur

Why it matters

Gradual adoption: Drop Checkbox into existing form architectures without rewriting validation logic or state management. Perfect for terms acceptance and consent workflows.

Reactive Conditional Visibility

Try it: Select "Business" to see conditional checkbox appear

Checkbox supports conditional rendering through the visibleWhen prop. Fields render based on engine state—components query field values and make rendering decisions. Select "Business" account type to see the marketing checkbox appear instantly without manual state orchestration. This is part of Dashforge Reactive V2 architecture.

Live Preview

import { DashForm } from '@dashforge/forms';
import { Checkbox, Select } from '@dashforge/ui';

function AccountForm() {
  return (
    <DashForm 
      defaultValues={{ 
        accountType: '', 
        acceptTerms: false,
        acceptMarketing: false 
      }}
    >
      <Select
        name="accountType"
        label="Account Type"
        options={[
          { label: 'Personal', value: 'personal' },
          { label: 'Business', value: 'business' }
        ]}
      />

      <Checkbox
        name="acceptTerms"
        label="I accept the terms and conditions"
        rules={{ required: 'You must accept the terms' }}
      />

      {/* Marketing checkbox: renders only for business accounts */}
      <Checkbox
        name="acceptMarketing"
        label="Send me marketing updates"
        visibleWhen={(engine) => {
          const accountType = engine.getNode('accountType')?.value;
          return accountType === 'business';
        }}
      />
    </DashForm>
  );
}

// The Engine API provides:
// - getNode(name): Access any field's state
// - Component re-renders on dependency changes
// - Component makes rendering decision (engine provides state)

Why it matters

Build adaptive forms where checkbox visibility responds to user input. The component handles conditional rendering—you define the predicate. Perfect for consent workflows that vary by user context.

API Reference

Complete props and type definitions

Explicit vs Auto-Bound Props: When inside DashForm, Checkbox receives checked, error, helperText, onChange, and onBlur automatically through field binding. Explicit props always take precedence over form-provided values.

Prop	Type	Default	Description
name	string	-	Field name for form integration (required)
label	React.ReactNode	-	Label text displayed next to the checkbox. When provided, wraps the checkbox in FormControlLabel.
checked	boolean	-	Controlled checked state of the checkbox
onChange	(event) => void	-	Callback fired when the checked state changes
error	boolean	false	If true, displays error state. Explicit error prop overrides form-provided error state. When inside DashForm without explicit prop, error is gated (shows only when touched OR submitted).
helperText	string	-	Helper text displayed below checkbox. Explicit helperText prop overrides form-provided validation error message. When inside DashForm, validation errors display as helperText (gated by touched/submitted state).
disabled	boolean	false	If true, the checkbox is disabled
rules	ValidationRules	-	Validation rules for DashForm integration. Format follows React Hook Form rules contract. Only used when inside DashForm—ignored in standalone mode. Common rule: { required: "message" } for mandatory acceptance.
visibleWhen	(engine: Engine) => boolean	-	Component-level conditional rendering predicate. Receives engine instance with access to all field state via getNode(name). When false, component renders null. Re-evaluates on dependency changes. Only works inside DashForm (requires engine).

Under the hood

How Checkbox works internally

Form integration

Automatically binds to form state inside DashForm. No Controller, no manual wiring. Works as a standard MUI Checkbox when used standalone.

Behavior model

Returns boolean values (true/false). Errors appear only after blur or submit. Supports conditional visibility via visibleWhen—show/hide based on other field values.

Architecture

Built on MUI Checkbox with FormControlLabel for label association. Fully typed with TypeScript. Purpose-built for terms acceptance, consent workflows, settings toggles, and feature opt-ins.