@versini/ui-toggle

An accessible and customizable React toggle switch component built with TypeScript and TailwindCSS.

The Toggle component provides an intuitive switch interface for binary choices with comprehensive accessibility features and customizable styling options.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• ♿ Accessible: WCAG compliant with proper ARIA attributes and keyboard navigation
• 🎨 Customizable: Multiple sizes, themes, and styling options
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 🌲 Tree-shakeable: Lightweight and optimized for bundle size
• ⌨️ Keyboard Friendly: Full keyboard navigation support

Installation

npm install @versini/ui-toggle

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Basic Toggle

import { Toggle } from "@versini/ui-toggle";

function App() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Toggle
      label="Enable notifications"
      checked={enabled}
      onChange={setEnabled}
    />
  );
}

Toggle with Description

import { Toggle } from "@versini/ui-toggle";

function App() {
  return (
    <Toggle
      label="Dark mode"
      labelHidden={false}
      helperText="Switch between light and dark theme"
      checked={darkMode}
      onChange={setDarkMode}
    />
  );
}

Label Position

import { Toggle } from "@versini/ui-toggle";

function App() {
  return (
    <div className="space-y-4">
      {/* Default - label on the right */}
      <Toggle label="Notifications" checked={enabled} onChange={setEnabled} />

      {/* Label on the left */}
      <Toggle
        label="Notifications"
        labelPosition="left"
        checked={enabled}
        onChange={setEnabled}
      />
    </div>
  );
}

Examples

Settings Panel

import { Toggle } from "@versini/ui-toggle";

function SettingsPanel() {
  const [settings, setSettings] = useState({
    notifications: true,
    autoSave: false,
    darkMode: true
  });

  return (
    <div className="space-y-4">
      <Toggle
        label="Push notifications"
        checked={settings.notifications}
        onChange={(checked) =>
          setSettings({ ...settings, notifications: checked })
        }
      />
      <Toggle
        label="Auto-save"
        checked={settings.autoSave}
        onChange={(checked) => setSettings({ ...settings, autoSave: checked })}
      />
      <Toggle
        label="Dark mode"
        checked={settings.darkMode}
        onChange={(checked) => setSettings({ ...settings, darkMode: checked })}
      />
    </div>
  );
}

API

Toggle Props

| Prop | Type | Default | Description | | --------------- | ----------------------------------------------- | ---------- | ----------------------------------------------------------------- | | label | string | - | Visible (or aria) label for the toggle (required). | | name | string | - | Form field name (required). | | onChange | (checked: boolean) => void | - | Callback fired when checked state changes. | | checked | boolean | false | Controlled checked state. | | focusMode | "dark" \| "light" \| "system" \| "alt-system" | "system" | Focus ring color mode. | | labelHidden | boolean | false | Visually hide the label (still accessible). | | labelPosition | "left" \| "right" | "right" | Position of the label relative to the toggle. | | mode | "dark" \| "light" \| "system" \| "alt-system" | "system" | Color mode/theme. | | noBorder | boolean | false | Remove outer border styling. | | narrow | boolean | false | Render the toggle in narrow style (smaller height, longer width). | | noHaptic | boolean | false | Disable haptic feedback on toggle (mobile devices). | | className | string | - | Extra classes for wrapper. | | labelMode | "dark" \| "light" \| "system" \| "alt-system" | - | Label color mode. |

The component renders a native checkbox input – you can pass standard input attributes via spreading if extending.