Developer Docs
Quick reference guides with props tables, usage examples, and best practices for rapid development
Toggle
Toggle switch with moving dot animation
Toggle Component
A toggle switch component using CSS variables (--vwf-color, --vwf-size) for flexible theming. Built on native checkbox for accessibility with smooth animations and validation support. Includes ToggleGroup component for mutually exclusive options with button-style toggles.
🔧 Props
| Prop | Type | Default | Description |
|---|---|---|---|
| id | string | auto-generated | Unique identifier (format: toggle-{timestamp}-{random}) |
| label | string | undefined | Label text for the toggle |
| checked | State<boolean> | boolean | false | Current toggle state (on/off) |
| disabled | boolean | false | Whether toggle is disabled |
| required | boolean | false | Whether toggle is required (shows asterisk) |
| message | Object | undefined | Validation message {code: "info"|"success"|"warning"|"error", detail: string} |
| onchange | Function | undefined | Change event handler (receives event) |
| class | string | "" | Switch element classes (override defaults via filterClassName) |
| containerClass | string | "" | Outer container classes |
| wrapperClass | string | "vwfsize-md vwfcolor-sky" | Wrapper classes (use for vwfsize-* and vwfcolor-* utilities) |
| labelClass | string | "" | Label text classes |
| dotClass | string | "" | Moving dot element classes |
| msgClass | string | "" | Validation message container classes |
| children | Element[] | [] | Additional content in label area (e.g., status text, icons) |
💻 Basic Usage
Simple toggle switch with label and state management.
const notifications = van.state(true);
const autoSave = van.state(false);
Toggle({
label: 'Enable notifications',
checked: notifications,
onchange: () => notifications.val = !notifications.val
})
Toggle({
label: 'Enable auto-save',
checked: autoSave,
onchange: () => autoSave.val = !autoSave.val
})📏 Size Variants
Use wrapperClass with vwfsize-* utilities for different sizes. Dot and switch scale proportionally.
// Extra small
Toggle({
label: 'Extra Small',
wrapperClass: 'vwfsize-xs',
checked: state
})
// Small
Toggle({
label: 'Small',
wrapperClass: 'vwfsize-sm',
checked: state
})
// Medium (default)
Toggle({ label: 'Medium', checked: state })
// Large
Toggle({
label: 'Large',
wrapperClass: 'vwfsize-lg',
checked: state
})
// Extra large
Toggle({
label: 'Extra Large',
wrapperClass: 'vwfsize-xl',
checked: state
})🎨 Color Customization
Use wrapperClass with vwfcolor-* utilities to customize the toggle color when checked.
Toggle({
label: 'Sunrise',
wrapperClass: 'vwfcolor-sunrise vwfsize-lg',
checked: state
})
Toggle({
label: 'Sky',
wrapperClass: 'vwfcolor-sky vwfsize-lg',
checked: state
})
Toggle({
label: 'Earth',
wrapperClass: 'vwfcolor-earth vwfsize-lg',
checked: state
})
Toggle({
label: 'Sunset',
wrapperClass: 'vwfcolor-sunset vwfsize-lg',
checked: state
})✅ Validation & Messages
Display validation messages with info, success, warning, or error states.
const accepted = van.state(false);
const message = van.state({ code: '', detail: '' });
Toggle({
label: 'Accept terms',
checked: accepted,
required: true,
message: message,
onchange: () => {
accepted.val = !accepted.val;
if (accepted.val) {
message.val = {
code: 'success',
detail: 'Thank you!'
};
} else {
message.val = {
code: 'error',
detail: 'Required'
};
}
}
})🖇️ ToggleGroup Component
A group of toggle buttons where only one can be active at a time. Great for view modes, priorities, or exclusive options.
View Mode
Notification Method
const viewMode = van.state('grid');
const notMethod = van.state('email');
// View mode toggle group
ToggleGroup({
options: [
{ value: 'grid', label: 'Grid', icon: 'oj-ux-ico-grid-view-large' },
{ value: 'list', label: 'List', icon: 'oj-ux-ico-list-rectangles' }
],
value: viewMode
})
// Notification method toggle group
ToggleGroup({
options: [
{ value: 'email', label: 'Email', icon: 'oj-ux-ico-email' },
{ value: 'sms', label: 'SMS', icon: 'oj-ux-ico-cell-phone' },
{ value: 'push', label: 'Push', icon: 'oj-ux-ico-notification' }
],
value: notMethod
})☑️ Custom Styled ToggleGroup
Customize ToggleGroup with containerClass, buttonClass, activeClass, and inactiveClass for complete control.
const priority = van.state('medium');
ToggleGroup({
options: [
{ value: 'low', label: 'Low' },
{ value: 'medium', label: 'Medium' },
{ value: 'high', label: 'High' }
],
value: priority,
containerClass: 'bg-gradient-to-r from-sky/10 to-earth/10 p-1 rounded-full',
buttonClass: 'px-6 py-2 rounded-full text-sm',
activeClass: 'bg-gradient-to-r from-sky to-earth text-white shadow-lg',
inactiveClass: 'text-midnight hover:bg-white/50'
})🚫 Disabled State
Toggle can be disabled in both checked and unchecked states.
// Disabled unchecked
Toggle({
label: 'Disabled (unchecked)',
checked: van.state(false),
disabled: true
})
// Disabled checked
Toggle({
label: 'Disabled (checked)',
checked: van.state(true),
disabled: true
})⚡️ Best Practices
✓ Do This
✓Use wrapperClass for size and color
- Apply vwfsize-* and vwfcolor-* utilities to wrapperClass for consistent theming.
✓Use ToggleGroup for mutually exclusive options
- When users should select one option from 2-5 choices (view modes, priorities).
✓Provide clear, action-oriented labels
- Use verbs like "Enable", "Show", "Allow" to indicate what the toggle controls.
✓Use validation messages for required toggles
- Display error messages when required toggles are not checked (e.g., terms acceptance).
✓Use children for status text or icons
- Pass additional elements as children to show current state (e.g., "Enabled", "Disabled").
✗ Avoid This
✗Don't use toggle for actions
- Toggles are for settings/preferences. Use buttons for actions like "Delete" or "Submit".
✗Don't use ambiguous labels
- Avoid labels like "Notifications" without context. Use "Enable notifications" instead.
✗Don't use ToggleGroup for more than 5 options
- For 6+ options, use RadioButton or Select component instead.
✗Don't apply size classes directly to class prop
- Use wrapperClass for vwfsize-* utilities. The class prop is for the switch element.
✨ Key Features
⭑CSS Variable Sizing
- Uses --vwf-size for proportional sizing. Switch width, height, and dot size all scale together.
⭑CSS Variable Coloring
- Uses --vwf-color for checked state color. Set via vwfcolor-* utilities on wrapperClass.
⭑Native Checkbox Pattern
- Built on native checkbox input for full accessibility. Screen readers announce toggle state correctly.
⭑GPU-Accelerated Animation
- Moving dot uses CSS transform (translateX) for smooth 60fps animation.
⭑Validation Message Display
- Shows validation messages with icons for info, success, warning, and error states.
⭑ToggleGroup Component
- Helper component for mutually exclusive toggles with button-style interface.
⭑Full Tailwind Override
- filterClassName enables complete customization of all elements (switch, dot, label, container).
⭑Disabled State Support
- Visual feedback with opacity and cursor changes. Works in both checked and unchecked states.
⭑Auto-Generated IDs
- Automatic unique ID generation prevents console errors when id prop not provided.
⭑Visual Focus States
- Focus ring with --vwf-color for keyboard navigation accessibility.
Explore More Components
Browse other component categories