The switch component is a toggle control that allows users to quickly turn an option on or off. Unlike checkboxes which are for selecting multiple options, switches are specifically designed for immediate state changes and binary choices. The component provides clear visual feedback for the current state and supports various sizes, validation states, and accessibility features.
✅ Use switches when:
- Controlling system settings or preferences (enable/disable features)
- Toggling between two distinct states with immediate effect
- Turning services, notifications, or modes on/off
- Managing visibility or availability of features
- Creating compact toggle controls in mobile interfaces
- Implementing preference panels and configuration screens
❌ Don't use switches for:
- Selecting multiple items from a list (use checkboxes instead)
- Single-choice selection from multiple options (use radio buttons)
- Form submissions where immediate action isn't intended
- Complex state changes requiring confirmation
- Navigation or triggering actions (use buttons instead)
- When the "off" state isn't meaningful or clear
Simple switches for immediate state toggles with clear labels:
Choose switch sizes based on your interface density and importance:
Switches support various states to communicate different conditions:
Flexible label and description placement for different layout requirements:
Use input groups to organize related switches with shared context:
Special styling options for enhanced visibility and emphasis:
The switch component is built with accessibility as a core principle:
- Space: Toggle switch state
- Enter: Alternative toggle (custom enhancement)
- Tab: Navigate between switches
- Shift + Tab: Navigate backwards
- Proper ARIA role (switch) for clear identification
- State announcements (on, off) with proper labels
- Form association and validation messages
- Group labeling for related switches
- Clear focus indicators that respect user preferences
- Logical tab order following visual layout
- Programmatic focus control for dynamic interfaces
- Use switches for immediate state changes and system preferences
- Use checkboxes for form selections and multi-item choices
- Consider the context: switches imply immediate action, checkboxes imply selection
- Maintain consistent sizing within related switch groups
- Use background variants on colored surfaces for better contrast
- Consider border emphasis for critical or high-impact settings
- Test with different themes and accessibility settings
- Ensure sufficient color contrast for all states
- Provide clear, descriptive labels that explain the effect
- Use descriptions to clarify what happens when toggled
- Group related switches with input groups
- Consider the cognitive load of too many switches
- Make the consequences of each switch state clear
- Test with real users and assistive technologies
- Always provide meaningful value attributes for form handling
- Implement proper validation for required switches
- Use appropriate feedback types for different validation states
- Consider the immediate vs. deferred action patterns
- Ensure switches work properly in forms and with validation
import { DapDSSwitch } from 'dap-design-system'
import { DapDSSwitchReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSSwitch } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
border | boolean | false | This sets up border around the switch, when true. |
type | 'normal', 'background' | 'normal' | The type of the switch |
feedbackId | feedback-${DapDSSwitch.nextId}-${uniqueSuffix} | ||
name | string | The name of the switch. | |
value | string | The value of the switch. | |
label | string | The label of the switch. | |
description | string | The description of the switch. | |
checked | boolean | The checked state of the switch. | |
size | 'xs', 'sm' , 'lg' | The size of the switch. | |
disabled | boolean | The disabled state of the switch. | |
readonly | boolean | Whether the switch is readonly (cannot be changed but value is submitted with form). | |
required | boolean | The required state of the switch. | |
labelPlacement | 'left', 'right' | The placement of the label. | |
descriptionPlacement | 'top', 'bottom' | The placement of the description. | |
subtle | boolean | The weight of the label. | |
feedback | string | The feedback of the switch. | |
feedbackType | 'negative', 'positive' , 'warning' | The feedback type of the switch. | |
optional | boolean | The optional state of the switch. | |
optionalLabel | string | The optional label of the switch. |
No slots available.
| Event Name | Description | Type |
|---|---|---|
dds-change | Fired when the input value changes. | {value: string } |
dds-blur | Emitted when the input loses focus. | {void } |
dds-focus | Emitted when the input gains focus. | {void } |
dds-input | Emitted when the input receives input. | {value: string } |
| Part Name | Description |
|---|---|
base | The main switch container. |
baselabel | The main label container |
label | The label of the switch. |
input | The native input of the switch. |
control | The control of the switch. |
description | The description of the switch. |
You can style CSS parts using the ::part() pseudo-element selector:
/* Target a specific part */
.my-custom-dap-ds-switch::part(base) {
/* Your custom styles */
}
/* Target multiple parts */
.my-custom-dap-ds-switch::part(base),
.my-custom-dap-ds-switch::part(baselabel) {
/* Shared styles */
}
Example usage:
<dap-ds-switch class="my-custom-dap-ds-switch">
Switch
</dap-ds-switch>
.my-custom-dap-ds-switch::part(base) {
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.
No CSS custom properties available.
