ToggleField

Description

A toggle switch field component that provides a visual switch interface for boolean or binary (0/1) values. Features two sizes and configurable label text for the on/off states.

Import

import { ToggleField } from '@components/common/form/ToggleField';

Usage

import { Form } from '@components/common/form/Form';
import { ToggleField } from '@components/common/form/ToggleField';

function SettingsForm() {
  return (
    <Form action="/api/settings">
      <ToggleField
        name="emailNotifications"
        label="Email Notifications"
        defaultValue={true}
      />
    </Form>
  );
}

Props

Name	Type	Default	Description
name	FieldPath<T>	-	Field name (required)
label	string	-	Label text displayed above the toggle
trueValue	boolean | 1	true	Value when toggle is on
falseValue	boolean | 0	false	Value when toggle is off
trueLabel	string	'Yes'	Label text when toggle is on
falseLabel	string	'No'	Label text when toggle is off
size	'sm' | 'default'	'default'	Size of the toggle switch
defaultValue	boolean | 0 | 1	false	Default toggle state
disabled	boolean	false	Disables the toggle
required	boolean	false	Makes the field required
error	string	-	Custom error message
helperText	string	-	Helper text shown in a tooltip
validation	RegisterOptions<T>	-	React Hook Form validation rules
onChange	(value: boolean | 0 | 1) => void	-	Callback fired when the value changes
wrapperClassName	string	-	CSS class for the wrapper div

Example: Boolean Values

import { Form } from '@components/common/form/Form';
import { ToggleField } from '@components/common/form/ToggleField';

function NotificationSettings() {
  return (
    <Form action="/api/notifications">
      <ToggleField
        name="emailEnabled"
        label="Email Notifications"
        trueLabel="Enabled"
        falseLabel="Disabled"
        defaultValue={true}
      />
      
      <ToggleField
        name="smsEnabled"
        label="SMS Notifications"
        trueLabel="On"
        falseLabel="Off"
      />
    </Form>
  );
}

Example: Binary Values (0/1)

import { Form } from '@components/common/form/Form';
import { ToggleField } from '@components/common/form/ToggleField';

function ProductForm() {
  return (
    <Form action="/api/products">
      <ToggleField
        name="isPublished"
        label="Product Status"
        trueValue={1}
        falseValue={0}
        trueLabel="Published"
        falseLabel="Draft"
        defaultValue={0}
      />
    </Form>
  );
}

Example: Different Sizes

import { Form } from '@components/common/form/Form';
import { ToggleField } from '@components/common/form/ToggleField';

function SizeDemo() {
  return (
    <Form action="/api/settings">
      <ToggleField
        name="setting1"
        label="Small Toggle"
        size="sm"
      />
      
      <ToggleField
        name="setting2"
        label="Default Toggle"
        size="default"
      />
    </Form>
  );
}

Example: With Callback

import { Form } from '@components/common/form/Form';
import { ToggleField } from '@components/common/form/ToggleField';
import { useState } from 'react';

function FeatureToggle() {
  const [isEnabled, setIsEnabled] = useState(false);

  return (
    <Form action="/api/features">
      <ToggleField
        name="feature"
        label="Advanced Features"
        onChange={(value) => {
          setIsEnabled(Boolean(value));
          console.log('Feature toggled:', value);
        }}
        helperText={isEnabled ? 'Advanced features are active' : 'Enable to access more features'}
      />
    </Form>
  );
}

Size Options

• sm: 14 x 24 px
• default: 18.4 x 32 px — the default

Features

• Visual Feedback: Animated switch with smooth transitions
• Flexible Values: Support for boolean or binary (0/1) values
• Custom Labels: Different labels for on/off states
• Size Control: Two size options
• Controller Integration: Uses React Hook Form Controller
• Accessibility: Includes ARIA attributes and screen reader support
• TypeScript Support: Full type safety with generics

Styling

The toggle uses Tailwind CSS classes and includes:

• Focus ring for keyboard navigation
• Smooth color transitions
• Disabled state styling
• Error state styling with red ring

Related Components

• Form - Parent form component
• CheckboxField - Checkbox input
• RadioGroupField - Radio button selection