Switch

Switch is a themed on/off toggle built on Roblox's native ImageButton: a pill-shaped track with a circular thumb that slides between an off (left) and on (right) position.

Import

import { Switch } from "@rbxts/react-clean-ui";

Basic usage

The switch starts off by default.

Uncontrolled

Leave checked unset and the switch keeps its own state. Use defaultChecked to choose the starting value.

<Switch defaultChecked />

<Switch
    defaultChecked={true}
    onChange={(checked) => {
        print(`Checked: ${checked}`);
    }}
/>

defaultChecked is only read when the switch mounts. Changing it later has no effect.

Controlled

Pass checked to drive the switch from your own state, the same contract as Checkbox. Clicking it calls onChange with the requested value but changes nothing by itself, so feed the value back through checked.

import React, { useState } from "@rbxts/react";
import { Switch } from "@rbxts/react-clean-ui";

export function ControlledSwitch() {
    const [enabled, setEnabled] = useState(false);

    return (
        <Switch
            checked={enabled}
            onChange={setEnabled}
        />
    );
}

The thumb animates whenever the checked prop changes, including when you change it from elsewhere. Changing checked from outside does not call onChange.

With a fieldset

Use Fieldset.Control and Fieldset.Label to associate the switch with a label.

<Fieldset checkbox>
    <Fieldset.Control>
        <Switch
            onChange={(checked) => {
                print(`Checked: ${checked}`);
            }}
        />
    </Fieldset.Control>

    <Fieldset.Label>
        <Text text="Enable notifications" />
    </Fieldset.Label>
</Fieldset>

When the user clicks either the switch or its label, the checked state toggles.

Intents

Set intent to control the track's on-state (checked) background and border colors.

<Switch defaultChecked intent="success" />
<Switch defaultChecked intent="danger" />

The off-state track color is always the theme's static color, regardless of intent. There is no hover state.

Disabled state

Set disabled to prevent interaction. The track and thumb render at a flat, dimmed transparency, and both clicking the switch and activating a paired Fieldset.Label are ignored.

<Switch defaultChecked disabled />
<Switch disabled />

A disabled switch never calls onChange. A controlled switch can still be changed through checked while disabled.

Ordering in a layout

Use LayoutOrder to position the switch inside a list layout such as VStack or HStack. When unset, Roblox's default (0) is used.

<VStack>
    <Switch LayoutOrder={1} defaultChecked />
    <Switch LayoutOrder={2} />
    <Switch LayoutOrder={3} intent="danger" />
</VStack>

Props

Switch-specific props

Shared props

The switch also supports props inherited from the following interfaces.

Behaviour

• The switch is off by default.
• With checked set, the switch is controlled: it shows checked, and a click calls onChange(!checked) without changing anything internally. Without checked, it starts at defaultChecked and flips its own state on each click before calling onChange.
• Clicking the switch, or a paired Fieldset.Label, toggles it, unless disabled.
• onChange only fires in response to a user toggle. It never fires on mount, never fires when a controlled checked prop changes, and never fires while disabled.
• The thumb's horizontal position and the track's background/border colors animate together, driven by a single tween progress value, over theme.components.switch.animation.duration seconds. A duration of 0 snaps instantly instead of animating.
• The on-state track/border colors are resolved from intent (layered over theme.colors.intents); the off-state colors are always the theme's static, non-intent colors.
• When disabled, both the track and thumb render at a flat dimmed transparency, overriding rather than blending with their normal transparency.
• The thumb's diameter is derived from the track height and its inset, not independently configurable.

The state transitions follow this pattern:

false → true → false

Theme values

The switch uses values from theme.components.switch for:

• The track's fixed width and height (the switch does not auto-size or accept size override props)
• Corner radius and border thickness of the track
• The transparency applied to both track and thumb while disabled
• The tween duration used to animate the thumb position and track colors
• The off-state track background color, background transparency, and border color
• Optional per-intent color overrides for the on-state track/border colors, layered on top of theme.colors.intents
• The thumb's inset from the track edge (which also determines its diameter), corner radius, background color, background transparency, border color, border thickness, and box shadow

These values can be changed by providing a custom Clean UI theme.