Switch - Semi Design Next

Demos

How to import

import { Switch } from '@fibrous/semi-ui-react';

Basic Usage

You can monitor state changes through onChange, and set the selected state through defaultChecked or controlled checked.
Use aria-label to describe the specific function of the Switch

Code

import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch onChange={(v) => console.log(v)} aria-label="a switch for demo" />
            <br />
            <Switch defaultChecked onChange={(v) => console.log(v)} aria-label="a switch for semi demo" />
        </div>
    );
}

Size

Code

import { Switch, Space } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Space style={{ marginBottom: 10, display: 'block' }}>
                <Switch size="small" aria-label="a switch for demo" />
                <Switch defaultChecked size="small" aria-label="a switch for demo" />
                <Switch size="small" loading aria-label="a switch for demo" />
                <Switch size="small" loading defaultChecked aria-label="a switch for demo" />
            </Space>
            <Space style={{ marginBottom: 10, display: 'block' }}>
                <Switch aria-label="a switch for demo" />
                <Switch defaultChecked aria-label="a switch for demo" />
                <Switch loading aria-label="a switch for demo" />
                <Switch loading defaultChecked aria-label="a switch for demo" />
            </Space>
            <Space>
                <Switch size="large" aria-label="a switch for demo" />
                <Switch defaultChecked size="large" aria-label="a switch for demo" />
                <Switch size="large" loading aria-label="a switch for demo" />
                <Switch size="large" loading defaultChecked aria-label="a switch for demo" />
            </Space>
        </div>
    );
}

Disabled

Code

import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch disabled aria-label="a switch for demo" />
            <br />
            <Switch disabled checked aria-label="a switch for demo" />
        </div>
    );
}

With text

Can pass checkedText with uncheckedText Text when setting the switch
The long text is recommended to be placed directly on the outside.
Note: This does not work with the smallest switch (size = 'small')

Code

import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch aria-label="带开关文字的开关" checkedText="开" uncheckedText="关" />
            <Switch aria-label="带符号文字的开关" checkedText="｜" uncheckedText="〇" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="带开关文字的开关，已开启" defaultChecked checkedText="开" uncheckedText="关" />
            <Switch aria-label="带符号文字的开关，已开启" defaultChecked checkedText="｜" uncheckedText="〇" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="大号带开关文字的开关" checkedText="开" uncheckedText="关" size="large" />
            <Switch aria-label="大号带符号文字的开关" checkedText="｜" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="大号带开关文字的开关，已开启" defaultChecked checkedText="开" uncheckedText="关" size="large" />
            <Switch aria-label="大号带符号文字的开关，已开启" defaultChecked checkedText="｜" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
        </div>
    );
}

Compared to setting the embedded text through checkedText and uncheckedText, we recommend placing the text description outside the Switch

已关闭

Code

import { useState } from 'react';
import { Switch, Typography } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    const [open, setOpen] = useState<boolean>();
    const { Title } = Typography;
    return (
        <div style={{ display: 'flex', alignItems: 'center' }}>
            <Title heading={6} style={{ margin: 8 }}>
                {open ? '已开启' : '已关闭'}
            </Title>
            <Switch checked={open} onChange={setOpen} aria-label="a switch for demo" />
        </div>
    );
}

Controlled component

Whether the component is selected depends entirely on the incoming checked value, used with onChange

Code

import { useState } from 'react';
import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    const [checked, setChecked] = useState(true);

    const onChange = (checked: boolean) => {
        setChecked(checked);
    };

    return <Switch checked={checked} aria-label="a switch for demo" onChange={onChange} />;
}

loading

You can turn on the loading state by setting loading="true".

Code

import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch loading aria-label="Loading switch" />
            <br />
            <Switch loading defaultChecked aria-label="Loading switch, on" />
        </div>
    );
}

API reference

Props

Property	Description	Type	Default
checked	Checked state. When not `undefined` it is controlled: the value decides what is shown, and a click only calls onChange, so update the value in the callback. Setting it back to `undefined` unchecks the switch and makes it uncontrolled.	`boolean`	-
checkedText	Content shown when checked. Not shown when size is `small`.	`React.ReactNode`	-
className	Class name of the root element.	`string`	`""`
defaultChecked	Initial checked state when uncontrolled. Read only once, on the first render.	`boolean`	-
disabled	Whether the switch is disabled.	`boolean`	`false`
id	Id of the native input.	`string`	-
loading	Whether the switch is loading. While loading, the input stays focusable with `aria-disabled`; toggles are ignored and onChange is not called.	`boolean`	`false`
name	Name of the native input, used when the form is submitted.	`string`	-
onChange	Called when the user toggles the switch, with the new checked state and the native change event. Not called while loading.	`Type`	-
onMouseEnter	Called when the pointer enters the root element.	`Type`	-
onMouseLeave	Called when the pointer leaves the root element.	`Type`	-
ref	Reference to the root `div` element.	`Type`	-
size	Switch size: `large`, `default` or `small`.	`Size`	`"default"`
style	Style of the root element.	`React.CSSProperties`	-
tabIndex	tabIndex of the native input.	`number`	-
uncheckedText	Content shown when unchecked. Not shown when size is `small`.	`React.ReactNode`	-

className, style, ref, onFocus, onBlur and other native attributes (such as data-*) land on the root element; onFocus and onBlur receive the focus events bubbling up from the inner input. autoFocus and aria-* land on the inner native input.

Accessibility

ARIA

The inner input of Switch has a switch role, and its on or off state is expressed by the native checked state of the input.
As a form field, it should have a Label.

The Label is added automatically when you use Form.Switch. If you use Switch alone, it is recommended to use aria-label to describe the current label function.

Keyboard and Focus

Keyboard users can use Tab and Shift + Tab to switch focus.
When focusing, you can switch on or off by pressing the Space key.

Content Guidelines

Switch description
- First letter is capitalized, no punctuation is required
- Indirectly and explicitly state whether the setting is on or off
- If needed, explain to the user what the on and off states represent

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$transition_duration-switch-bg	200ms	开关-背景色-动画持续时间
$transition_function-switch-bg	var(--semi-transition_function-easeIn)	开关-背景色-过渡曲线
$transition_delay-switch-bg	var(--semi-transition_delay-none)	开关-背景色-延迟时间
$spacing-switch_unchecked-translateX	2px	未选中态开关滑块位移距离
$spacing-switch_spin_unchecked-translateX	2px	未选中态加载图标位移距离
$spacing-switch_checked-translateX	18px	选中态开关滑块位移距离
$spacing-switch_spin_checked-translateX	16px	选中态加载图标位移距离
$spacing-switch_expand_large-translateX	10px
$spacing-switch_unchecked_large-translateX	3px	大尺寸未选中态开关滑块位移距离
$spacing-switch_spin_unchecked_large-translateX	2px	大尺寸未选中态加载图标位移距离
$spacing-switch_checked_large-translateX	26px	大尺寸选中态开关滑块位移距离
$spacing-switch_spin_checked_large-translateX	22px	大尺寸选中态加载图标位移距离
$spacing-switch_expand_small-translateX	2px
$spacing-switch_unchecked_small-translateX	1px	小尺寸未选中态开关滑块位移距离
$spacing-switch_spin_unchecked_small-translateX	2px	小尺寸未选中态加载图标位移距离
$spacing-switch_checked_small-translateX	11px	小尺寸选中态开关滑块位移距离
$spacing-switch_spin_checked_small-translateX	10px	小尺寸选中态加载图标位移距离
$motion-switch-transitionDuration	200ms	开关动画时长
$color-switch_default-bg-default	var(--semi-color-fill-0)	关闭态(未选中)开关背景色 - 默认
$color-switch_default-bg-hover	var(--semi-color-fill-1)	关闭态开关背景色 - 悬浮
$color-switch_default-bg-active	var(--semi-color-fill-2)	关闭态开关背景色 - 按下
$color-switch_default-border-default	transparent	关闭态开关描边颜色
$color-switch_checked-bg-default	var(--semi-color-success)	开启态开关背景色 - 默认
$color-switch_checked-bg-hover	var(--semi-color-success-hover)	开启态开关背景色 - 悬浮
$color-switch_checked-bg-active	var(--semi-color-success-active)	开启态开关背景色 - 按下
$color-switch_disabled-bg-default	transparent	禁用态开关背景色
$color-switch_disabled-bg-hover	transparent	禁用态开关背景色 - 悬浮
$color-switch_disabled-bg-active	transparent	禁用态开关背景色 - 按下
$color-switch_disabled-border-default	var(--semi-color-border)	禁用态开关描边颜色
$color-switch_disabled-bg-hover	transparent	禁用态开关背景色 - 悬浮
$color-switch_checked_disabled-bg-default	var(--semi-color-success-disabled)	禁用开启态开关背景颜色
$color-switch_checked_disabled-border-default	transparent	禁用开启态开关描边颜色
$color-switch_knob-bg-default	var(--semi-white)	开关滑块背景颜色 - 关闭态
$color-switch_knob-bg-checked	var(--semi-white)	开关滑块背景颜色 - 开启态
$color-switch_knob-border-default	var(--semi-color-border)	开关滑块描边颜色
$color-switch_checked-text-default	var(--semi-color-white)	开启态开关文案颜色
$color-switch_unchecked-text-default	var(--semi-color-text-2)	关闭态开关文案颜色
$color-switch_loading_spin-default	var(--semi-color-white)	加载态开关loading图标颜色
$color-switch_spin_checked-bg-default	var(--semi-color-success-hover)	已开启开关加载态loading背景颜色
$color-switch_spin_unchecked-bg-default	var(--semi-color-fill-1)	已关闭开关加载态loading背景颜色
$color-switch_primary-outline-focus	$color-focus-ring	开关轮廓 - 聚焦
$width-switch	40px	开关宽度
$height-switch	24px	开关高度
$width-switch_knob_expand	6px	开关滑块按压时延展宽度
$width-switch_knob_default	18px	开关滑块宽度
$width-switch_knob_active	$width-switch_knob_default + $width-switch_knob_expand	开关滑块按下态宽度
$height-switch_large	32px	大尺寸开关高度
$width-switch_large	54px	大尺寸开关宽度
$width-switch_knob_large	24px	大尺寸开关滑块宽度
$width-switch_knob_large_active	$width-switch_knob_large + $spacing-switch_expand_large-translateX	大尺寸开关滑块按下态宽度
$height-switch_small	16px	小尺寸开关高度
$width-switch_small	26px	小尺寸开关宽度
$width-switch_knob_large_small	12px	小尺寸开关滑块宽度
$width-switch_knob_small_active	$width-switch_knob_large_small + $spacing-switch_expand_small-translateX	小尺寸开关滑块按下态宽度
$width-switch_knob_disabled-border	1px	禁用态开关滑块边框宽度
$width-switch_checked_unchecked_text	26px	开关文案宽度
$width-switch_spin-small	10px	小尺寸开关加载 spin 宽度
$width-switch_spin-default	18px	默认尺寸开关加载 spin 宽度
$width-switch_spin-large	28px	大尺寸开关加载 spin 宽度
$width-switch-outline	$width-focus-ring	开关轮廓宽度
$spacing-switch_knob-padding	2px	开关滑块顶部边距
$spacing-switch_knob_large-padding	3px	大尺寸开关滑块顶部边距
$spacing-switch_knob_small-padding	1px	小尺寸开关滑块顶部边距
$spacing-switch_knob-left	0px	开关滑块左侧偏移距离
$radius-switch	$height-switch * 0.5	开关圆角
$radius-switch_large	$height-switch_large * 0.5	大尺寸开关圆角
$radius-switch_small	$height-switch_small * 0.5	小尺寸开关圆角