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

Theme previews

Installation

npm

npm install @rcarls/rc-switch

Yarn

yarn add @rcarls/rc-switch

import '@rcarls/rc-switch/define';

Markup

<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. rc-switch adds role="switch" only when the input does not already have a role.

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.

Live demo

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.

Methods

No public methods are documented in the custom elements manifest.

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.