Usage

import { Toggle } from "@opengovsg/oui"

<Toggle>Enable notifications</Toggle>

The Toggle component allows users to switch between two states (on/off). It is built on React Aria's Switch.

If the component does not have a visible label (by passing children), an aria-label prop must be passed instead to identify it to assistive technology.

Examples

With Label

Pass children to add a visible text label next to the toggle.

Label Placement

Use the labelPlacement prop to position the label before or after the toggle. Defaults to "end".

Sizes

Use the size prop to change the size of the toggle. Defaults to "md".

Thumb Icon

Use the thumbIcon prop to display an icon inside the toggle thumb. The prop accepts a React element or a render function that receives SwitchRenderProps (including isSelected and className).

Disabled

Use the isDisabled prop to disable the toggle.

Controlled

Use the isSelected and onChange props to control the toggle state programmatically.

Events

Toggle supports the following event handlers, inherited from React Aria's Switch:

• onChange — Called when the selection state changes, receiving a boolean.
• onFocus / onBlur — Called when the toggle gains or loses focus.
• onFocusChange — Called when the focus state changes, receiving a boolean.
• onKeyDown / onKeyUp — Called on keyboard events.
• onHoverStart / onHoverEnd / onHoverChange — Called on hover events.

Accessibility

• Built on the WAI-ARIA switch role, providing correct semantics for assistive technology.
• Keyboard interaction: Press Space to toggle the switch state.
• Label is automatically associated with the switch input.
• Disabled and selected states are exposed to assistive technology.
• If no visible label is provided via children, an aria-label prop must be set.

Slots

• base: The root container wrapper with label.
• track: The toggle track (background).
• thumb: The toggle thumb (sliding circle).
• thumbIcon: The icon inside the thumb.

Custom Styles

You can customize the Toggle component by passing custom Tailwind CSS classes to the component slots via the classNames prop.

Props

Toggle