Switch

A cross-platform toggle for binary on/off settings; a visual alternative to a checkbox.

Installation

npm install @xsolla/xui-switch

Imports

import { Switch } from "@xsolla/xui-switch";
import type { SwitchProps } from "@xsolla/xui-switch";

Quick start

const [enabled, setEnabled] = useState(false);

<Switch
  checked={enabled}
  onValueChange={setEnabled}
  label="Enable notifications"
/>;

API Reference

<Switch>

| Prop | Type | Default | Description | | ---------------- | ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | checked | boolean | false | Whether the switch is on. | | size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Size of the switch. | | state | 'default' \| 'hover' \| 'disable' \| 'error' | 'default' | Visual state. | | disabled | boolean | false | Disable the switch. | | label | string | — | Label text shown next to the switch. | | labelPosition | 'left' \| 'right' | 'right' | Position of the label. | | description | string | — | Description text below the label. | | errorLabel | string | — | Error message shown when state === 'error'. | | onValueChange | (value: boolean) => void | — | Fired when toggled. | | ariaLabel | string | — | Accessible label for screen readers. | | ariaLabelledBy | string | — | ID of an element that labels the switch. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Examples

With description

const [darkMode, setDarkMode] = useState(false);

<Switch
  checked={darkMode}
  onValueChange={setDarkMode}
  label="Dark mode"
  description="Enable dark theme across the application"
/>;

Label positions

<Switch label="Label on the right" labelPosition="right" />
<Switch label="Label on the left" labelPosition="left" />

Sizes

<Switch size="sm" label="Small" checked />
<Switch size="md" label="Medium" checked />
<Switch size="lg" label="Large" checked />
<Switch size="xl" label="Extra large" checked />

Error state

<Switch
  checked={false}
  state="error"
  label="Required setting"
  errorLabel="This setting must be enabled to continue"
/>

Disabled

<Switch state="disable" label="Disabled off" />
<Switch state="disable" checked label="Disabled on" />

Accessibility

• Uses role="switch" and aria-checked to reflect state.
• Space and Enter toggle the switch.
• description and errorLabel are linked via aria-describedby.
• Disabled state is announced to assistive technology.