rc-switch
Switch wrapper that enhances a native <input type="checkbox">.
- Package
@rcarls/rc-switch- Element
<rc-switch>- Native dependency
- Direct-child native checkbox
- State model
- Controlled or uncontrolled checked state
- Main events
rc-switch-change- Related
- Usage rulesTheme previews
Installation
- npm
- Yarn
- pnpm
npm install @rcarls/rc-webcomponents@next
yarn add @rcarls/rc-webcomponents@next
pnpm add @rcarls/rc-webcomponents@next
import '@rcarls/rc-webcomponents/rc-switch/define';
Usage
<label for="dark-mode">Dark mode</label>
<rc-switch>
<input id="dark-mode" name="darkMode" type="checkbox" />
</rc-switch>
The native checkbox stays in light DOM for labels, forms, validation, reset, and no-JavaScript fallback.
Live demo
Accessibility
rc-switch adds role="switch" to the checkbox only when the input does not already have a
role, so the checked state is announced as on or off. The checkbox keeps its keyboard behavior:
Space toggles it. The track, thumb, and icons are decorative. See the
WAI-ARIA Switch pattern.
Theming
Without a theme, the native checkbox remains visible. Packaged themes hide its visual box and enable the component's track, thumb, icons, and motion while leaving the checkbox connected and interactive.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | Not specified | Current checked state. Host writes are silent. |
defaultChecked | default-checked | boolean | Not specified | Initial checked state for uncontrolled usage. |
disabled | disabled | boolean | false | Mirror disabled state to the native checkbox. |
icons | icons | boolean | false | Show selected and deselected icon affordance containers. |
showOnlySelectedIcon | show-only-selected-icon | boolean | false | Show only the selected icon affordance container. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-switch-change | No detail type documented | Fired after user interaction changes the checked state. |
Slots
| Name | Description |
|---|---|
(default) | A direct native `<input type="checkbox">` child. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-switch-track-inline-size | Not specified | Track inline size. No built-in default; a theme must set this for the switch to render with a visible size. |
--rc-switch-track-block-size | Not specified | Track block size. No built-in default; a theme must set this for the switch to render with a visible size. |
--rc-switch-native-appearance | revert | Slotted native checkbox `appearance`. |
--rc-switch-native-inline-size | revert | Slotted native checkbox inline size. |
--rc-switch-native-block-size | revert | Slotted native checkbox block size. |
--rc-switch-native-margin | revert | Slotted native checkbox margin. |
--rc-switch-native-opacity | revert | Slotted native checkbox opacity. |
--rc-switch-decoration-display | none | Display of the track/thumb/icon decoration. Themes set this to `block` (or similar) to opt into the decorated switch look. |
--rc-switch-track-border | 2px solid ButtonBorder | Track border. |
--rc-switch-track-radius | 9999px | Track and thumb border radius. |
--rc-switch-track-bg | ButtonFace | Unselected track background. |
--rc-switch-duration | 150ms | Track/thumb/icon transition duration. |
--rc-switch-easing | ease | Track/thumb/icon transition easing. |
--rc-switch-thumb-size | 1rem | Unselected thumb inline and block size. |
--rc-switch-thumb-offset | 0.375rem | Thumb and icon inline start offset within the track. |
--rc-switch-thumb-radius | 9999px | Thumb border radius. |
--rc-switch-thumb-bg | ButtonText | Unselected thumb background. |
--rc-switch-icon-size | 1rem | Selected/deselected icon container size. |
--rc-switch-icon-color | Canvas | Icon color. |
--rc-switch-icon-display | none | Display of the active icon container when `icons` or `show-only-selected-icon` is set. |
--rc-switch-selected-track-border-color | Highlight | Selected track border color. |
--rc-switch-selected-track-bg | Highlight | Selected track background. |
--rc-switch-selected-thumb-size | 1.5rem | Selected thumb inline and block size. |
--rc-switch-selected-thumb-bg | HighlightText | Selected thumb background. |
--rc-switch-thumb-translate | 1.125rem | Inline-axis translation applied to the thumb and icons when selected. |
--rc-switch-focus-ring | 2px solid Highlight | Track focus ring, shown on focus-within. |
--rc-switch-focus-ring-offset | 2px | Track focus ring offset. |
--rc-switch-disabled-opacity | 0.5 | Host opacity while `disabled`. |
CSS Parts
| Part | Description |
|---|---|
track | Visual switch track. |
thumb | Visual switch thumb. |
selected-icon | Optional selected-state icon container. |
deselected-icon | Optional deselected-state icon container. |