XDS — Design System

Switch@xds/core · XDSSwitch v0.0.13

Usage

A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.

ts
import {XDSSwitch} from '@xds/core/Switch'

Best practices

Guidance	Practices
Do	Use for settings that apply immediately — the toggle should take effect without a separate save action.
Do	Pair with a clear, concise label that describes the setting being controlled.
Don't	Use for options that require a form submission to take effect — use a checkbox instead.
Don't	Use a switch for multi-state values — it's strictly on/off.

Examples

Common configurations, variations, and states.

Switch — DisabledDisabled switch with label and description for gated features.

tsx
'use client';
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
import {XDSCenter} from '@xds/core/Center';
export default function SwitchDisabled() {
  const [value, setValue] = useState(false);
  return (
    <XDSCenter>
      <XDSSwitch
        label="Premium feature"
        description="Upgrade to enable this option"
        value={value}
        onChange={setValue}
        isDisabled
      />
    </XDSCenter>
  );
}

Switch — Settings PanelSettings panel with spread-spaced switches in a card.

tsx
'use client';
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Layout';
import {XDSCenter} from '@xds/core/Center';
export default function SwitchSettingsPanel() {
  const [notifications, setNotifications] = useState(false);
  const [darkMode, setDarkMode] = useState(true);
  const [autoSave, setAutoSave] = useState(false);
  return (
    <XDSCenter width={350}>
      <XDSCard>
        <XDSVStack gap={4}>
          <XDSSwitch
            label="Enable notifications"
            value={notifications}
            onChange={setNotifications}
            labelPosition="start"
            labelSpacing="spread"
          />
          <XDSSwitch
            label="Dark mode"
            value={darkMode}
            onChange={setDarkMode}
            labelPosition="start"
            labelSpacing="spread"
          />
          <XDSSwitch
            label="Auto-save"
            value={autoSave}
            onChange={setAutoSave}
            labelPosition="start"
            labelSpacing="spread"
          />
        </XDSVStack>
      </XDSCard>
    </XDSCenter>
  );
}

Switch — With DescriptionToggle with a label and supporting description text.

tsx
'use client';
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
import {XDSCenter} from '@xds/core/Center';
export default function SwitchWithDescription() {
  const [value, setValue] = useState(false);
  return (
    <XDSCenter>
      <XDSSwitch
        label="Dark mode"
        description="Switch to a darker color scheme for reduced eye strain."
        value={value}
        onChange={setValue}
      />
    </XDSCenter>
  );
}

Switch — With StatusSwitches with error, warning, and success validation states.

tsx
'use client';
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
import {XDSVStack} from '@xds/core/Layout';
import {XDSCenter} from '@xds/core/Center';
export default function SwitchWithStatus() {
  const [terms, setTerms] = useState(false);
  const [sharing, setSharing] = useState(true);
  const [twoFactor, setTwoFactor] = useState(true);
  return (
    <XDSCenter width={400}>
      <XDSVStack gap={6}>
        <XDSSwitch
          label="Accept terms and conditions"
          value={terms}
          onChange={setTerms}
          isRequired
          status={{
            type: 'error',
            message: 'You must accept the terms to continue',
          }}
        />
        <XDSSwitch
          label="Share usage data"
          description="Help us improve by sharing anonymous usage statistics"
          value={sharing}
          onChange={setSharing}
          status={{
            type: 'warning',
            message: 'This data may be shared with partners',
          }}
        />
        <XDSSwitch
          label="Two-factor authentication"
          value={twoFactor}
          onChange={setTwoFactor}
          status={{type: 'success', message: 'Your account is now more secure'}}
        />
      </XDSVStack>
    </XDSCenter>
  );
}

Showcase source

tsx
'use client';
import {XDSSwitch} from '@xds/core/Switch';
export default function SwitchShowcase() {
  return (
    <XDSSwitch
      label="Enable notifications"
      value={false}
      onChange={() => {}}
    />
  );
}

Usage

import {XDSSwitch} from '@xds/core/Switch'

Best practices

Guidance	Practices
Do	Use for settings that apply immediately — the toggle should take effect without a separate save action.
Do	Pair with a clear, concise label that describes the setting being controlled.
Don't	Use for options that require a form submission to take effect — use a checkbox instead.
Don't	Use a switch for multi-state values — it's strictly on/off.

tsx

'use client'; import {useState} from 'react'; import {XDSSwitch} from '@xds/core/Switch'; import {XDSCenter} from '@xds/core/Center'; export default function SwitchDisabled() { const [value, setValue] = useState(false); return ( <XDSCenter> <XDSSwitch label="Premium feature" description="Upgrade to enable this option" value={value} onChange={setValue} isDisabled /> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSSwitch} from '@xds/core/Switch'; import {XDSCard} from '@xds/core/Card'; import {XDSVStack} from '@xds/core/Layout'; import {XDSCenter} from '@xds/core/Center'; export default function SwitchSettingsPanel() { const [notifications, setNotifications] = useState(false); const [darkMode, setDarkMode] = useState(true); const [autoSave, setAutoSave] = useState(false); return ( <XDSCenter width={350}> <XDSCard> <XDSVStack gap={4}> <XDSSwitch label="Enable notifications" value={notifications} onChange={setNotifications} labelPosition="start" labelSpacing="spread" /> <XDSSwitch label="Dark mode" value={darkMode} onChange={setDarkMode} labelPosition="start" labelSpacing="spread" /> <XDSSwitch label="Auto-save" value={autoSave} onChange={setAutoSave} labelPosition="start" labelSpacing="spread" /> </XDSVStack> </XDSCard> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSSwitch} from '@xds/core/Switch'; import {XDSCenter} from '@xds/core/Center'; export default function SwitchWithDescription() { const [value, setValue] = useState(false); return ( <XDSCenter> <XDSSwitch label="Dark mode" description="Switch to a darker color scheme for reduced eye strain." value={value} onChange={setValue} /> </XDSCenter> ); }

tsx

'use client'; import {useState} from 'react'; import {XDSSwitch} from '@xds/core/Switch'; import {XDSVStack} from '@xds/core/Layout'; import {XDSCenter} from '@xds/core/Center'; export default function SwitchWithStatus() { const [terms, setTerms] = useState(false); const [sharing, setSharing] = useState(true); const [twoFactor, setTwoFactor] = useState(true); return ( <XDSCenter width={400}> <XDSVStack gap={6}> <XDSSwitch label="Accept terms and conditions" value={terms} onChange={setTerms} isRequired status={{ type: 'error', message: 'You must accept the terms to continue', }} /> <XDSSwitch label="Share usage data" description="Help us improve by sharing anonymous usage statistics" value={sharing} onChange={setSharing} status={{ type: 'warning', message: 'This data may be shared with partners', }} /> <XDSSwitch label="Two-factor authentication" value={twoFactor} onChange={setTwoFactor} status={{type: 'success', message: 'Your account is now more secure'}} /> </XDSVStack> </XDSCenter> ); }

tsx

'use client'; import {XDSSwitch} from '@xds/core/Switch'; export default function SwitchShowcase() { return ( <XDSSwitch label="Enable notifications" value={false} onChange={() => {}} /> ); }