Switch

An intelligent binary toggle component built on MUI Switch. Ideal for on/off state controls like feature toggles, preferences, notifications, and settings. Supports standalone usage, seamless DashForm integration with automatic field binding, validation error gating, and reactive visibility.

Quick Start

Copy & Paste

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

<Switch label="Enable notifications" name="notifications" />

Examples

Common Switch patterns and configurations

Basic

Binary toggle with label for settings

Enable notifications

<Switch label="Enable notifications" name="notifications" />

Checked by Default

Pre-enabled state for default preferences

Dark mode

<Switch label="Dark mode" name="darkMode" checked />

Disabled

Prevent interaction when locked by policy

Beta features

<Switch label="Beta features" name="beta" disabled />

Disabled and On

Show enabled state without toggle control

Auto-save (enabled by admin)

<Switch 
  label="Auto-save (enabled by admin)" 
  name="autoSave" 
  checked 
  disabled 
/>

Error State

Validation feedback for required toggles

Accept privacy policy

<Switch
  label="Accept privacy policy"
  name="privacy"
  error
  helperText="You must accept the privacy policy"
/>

Without Label

Standalone toggle for compact layouts

<Switch name="standalone" />

Dashforge Capabilities

Progressive adoption from controlled components to predictive forms

Switch 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

Switch 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

<Switch
  checked={isEnabled}
  onChange={(e) => setIsEnabled(e.target.checked)}
  label="Enable notifications"
/>

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>
  <Switch 
    name="notifications"
    label="Email notifications"
    rules={{ required: 'Please enable or disable' }}
  />
</DashForm>

Reactive Visibility

Available Now

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

Conditional rendering via visibleWhen

Engine evaluates the predicate

Useful for dependent settings

<Switch
  name="marketingEmails"
  label="Send marketing emails"
  visibleWhen={(engine) => 
    engine.getNode('emailsEnabled')?.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

<Switch
  name="featureEnabled"
  label="Feature Enabled"
  access={{
    resource: 'feature.toggle',
    action: 'edit',
    onUnauthorized: 'hide'
  }}
/>

Disable when cannot edit

<Switch
  name="isPublished"
  label="Published"
  access={{
    resource: 'article.publish',
    action: 'update',
    onUnauthorized: 'disable'
  }}
/>

Readonly for view-only

<Switch
  name="emailNotifications"
  label="Email Notifications"
  access={{
    resource: 'user.notifications.email',
    action: 'update',
    onUnauthorized: 'readonly'
  }}
/>

Combined with visibleWhen

<Switch
  name="requiresApproval"
  label="Requires Approval"
  visibleWhen={(e) => 
    e.getValue('workflowType') === true
  }
  access={{
    resource: 'workflow.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

Switch 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: Toggle switches and submit preferences

Switch integrates seamlessly with React Hook Form through DashForm. Components self-register, values sync automatically, and form submission captures all toggle states. Try toggling different notification preferences and submitting the form to see the complete state.

Live Preview

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

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

  return (
    <DashForm
      defaultValues={{ 
        emailNotifications: true,
        smsNotifications: false,
        pushNotifications: false
      }}
      onSubmit={handleSubmit}
      mode="onBlur"
    >
      <Switch
        name="emailNotifications"
        label="Email notifications"
      />
      <Switch
        name="smsNotifications"
        label="SMS notifications"
      />
      <Switch
        name="pushNotifications"
        label="Push notifications"
      />
      <button type="submit">Save Preferences</button>
    </DashForm>
  );
}

// Switch automatically:
// - Registers with React Hook Form
// - Syncs checked value from form state
// - Returns boolean values on submit
// - Tracks touched state on blur

Why it matters

Gradual adoption: Drop Switch into existing form architectures without rewriting state management. Perfect for preference panels, feature toggles, and settings screens.

Reactive Conditional Visibility

Try it: Select "Pro" plan to see advanced features switch appear

Switch supports conditional rendering through the visibleWhen prop. Fields render based on engine state—components query field values and make rendering decisions. Select "Pro" subscription plan to see the advanced features switch appear instantly without manual state orchestration. This is part of Dashforge Reactive V2 architecture.

Live Preview

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

function AccountSettings() {
  return (
    <DashForm 
      defaultValues={{ 
        plan: '',
        emailNotifications: false,
        advancedFeatures: false
      }}
    >
      <Select
        name="plan"
        label="Subscription Plan"
        options={[
          { label: 'Free', value: 'free' },
          { label: 'Pro', value: 'pro' }
        ]}
      />

      <Switch
        name="emailNotifications"
        label="Email notifications"
      />

      {/* Advanced features switch: renders only for Pro plan */}
      <Switch
        name="advancedFeatures"
        label="Enable advanced features"
        visibleWhen={(engine) => {
          const plan = engine.getNode('plan')?.value;
          return plan === 'pro';
        }}
      />
    </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 settings panels where toggle visibility responds to user selections. The component handles conditional rendering—you define the predicate. Perfect for tiered features and plan-dependent settings.

API Reference

Complete props and type definitions

Explicit vs Auto-Bound Props: When inside DashForm, Switch 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 switch. When provided, wraps the switch in FormControlLabel.
checked	boolean	-	Controlled checked state of the switch
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 switch. 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 switch 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. Useful for enforcing toggle requirements in specific contexts.
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 Switch works internally

Form integration

Automatically binds to form state inside DashForm. No Controller, no manual wiring. Works as a standard MUI Switch (with optional FormControlLabel) when used standalone.

Behavior model

Boolean values (true/false) for on/off states. Errors appear only after blur or submit. Supports reactive visibility via Reactive V2—conditionally show/hide based on other field values.

Architecture

Built on MUI Switch with FormControlLabel for labels. Fully typed with TypeScript. Purpose-built for feature toggles, notifications, settings, and any binary state control.