Browse docs

Checkbox

Single checkbox with optional label, helper text, and error state. Integrates with DashForm automatically — value is stored as a boolean.

Form-connected checkbox input built on top of Material-UI. Checkbox integrates automatically with DashForm and the Dashforge form engine. Registration, validation, error handling, reactive visibility, and RBAC orchestration are handled internally by the component. The component is designed for form-driven workflows rather than standalone state orchestration. The name prop is required to connect the field to the form schema and the internal form engine.

Quick Start

tsx

<Checkbox
  name="agree"
  label="I agree to the Terms of Service"
  rules={{ required: 'You must agree to continue' }}
/>

Examples

A checkbox bound to the form by name. The form stores a boolean.

I agree to the terms

<Checkbox name="agree" label="I agree to the terms" />

defaultChecked sets the initial value.

Subscribe to newsletter

<Checkbox name="newsletter" label="Subscribe to newsletter" defaultChecked />

Error state with helper text.

I agree to the terms

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

API

Prop	Type	Default	Description
`name`	`string`	—	Field name. Required.
`label`	`string`	—	Label text displayed next to the checkbox.
`defaultChecked`	`boolean`	`false`	Initial checked state (uncontrolled).
`disabled`	`boolean`	`false`	Disables the checkbox.
`error`	`boolean`	`false`	Error visual state.
`helperText`	`string`	—	Hint or error text below the checkbox.
`access`	`AccessRequirement`	—	RBAC access requirement. Controls visibility, disabled, and readonly state based on role permissions.
`rules`	`RegisterOptions`	—	React Hook Form validation rules.
`visibleWhen`	`VisibleWhenCondition`	—	Conditional visibility expression.

Notes

The stored form value is a boolean (true / false).
To require the checkbox to be checked, use rules={{ validate: (v) => v === true || 'Required' }}.

Capabilities

Checkbox supports progressive adoption — use it as a standalone controlled input, integrate with React Hook Form, or conditionally show it based on other form state.

Controlled

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

tsx

<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

tsx

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

Reactive Visibility

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

tsx

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

RBAC Access Control

Declarative role-based access control via the access prop. The component calls useAccessState(access) internally and maps the resolved permission to one of three field states — no if statements or manual checks needed in the parent.

The access prop accepts an AccessRequirement object:

Field	Type	Description
`resource`	`string`	The resource being protected (e.g. `'employee'`, `'invoice'`).
`action`	`string`	The action being checked (e.g. `'read'`, `'update'`, `'delete'`).
`onUnauthorized`	`'hide' \| 'disable' \| 'readonly'`	What to render when the user lacks permission. Defaults to `'hide'`.