Components
    Switch framework
    ReactVueSolidSvelte
    Switch language
    简体中文English
    GitHub
    Input · Switch

    Switch

    Switch is an interactive form used to switch two mutually exclusive states.

    Demos

    How to import

    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

    Basic Usage

    You can monitor state changes through onChange. A plain checked sets the initial state, which the user then toggles; to read and write the state, use bind:checked (see Controlled component).
    Use aria-label to describe the specific function of the Switch


    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';

    const log = (checked: boolean) => console.log(checked);
</script>

<div>
    <Switch aria-label="示例开关" onChange={log} />
    <br />
    <Switch aria-label="示例开关，初始开启" checked onChange={log} />
</div>

    Size

    Code
    <script lang="ts">
    import { Space, Switch } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Space style="display: block; margin-bottom: 10px">
        <Switch aria-label="小号开关" size="small" />
        <Switch aria-label="小号开关，已开启" checked size="small" />
        <Switch aria-label="小号开关，加载中" loading size="small" />
        <Switch aria-label="小号开关，已开启且加载中" checked loading size="small" />
    </Space>
    <Space style="display: block; margin-bottom: 10px">
        <Switch aria-label="默认开关" />
        <Switch aria-label="默认开关，已开启" checked />
        <Switch aria-label="默认开关，加载中" loading />
        <Switch aria-label="默认开关，已开启且加载中" checked loading />
    </Space>
    <Space>
        <Switch aria-label="大号开关" size="large" />
        <Switch aria-label="大号开关，已开启" checked size="large" />
        <Switch aria-label="大号开关，加载中" loading size="large" />
        <Switch aria-label="大号开关，已开启且加载中" checked loading size="large" />
    </Space>
</div>

    Disabled


    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Switch aria-label="不可用的开关" disabled />
    <br />
    <Switch aria-label="不可用的开关，已开启" checked disabled />
</div>

    With text

    checkedText and uncheckedText take snippets: define them with {#snippet} and pass them as props, or write them inside the Switch tag as snippets of the same name.
    Note: This does not work with the smallest switch (size = 'small')

    关
    〇


    开
    ｜


    关
    〇


    开
    ｜
    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

{#snippet on()}开{/snippet}
{#snippet off()}关{/snippet}
{#snippet bar()}｜{/snippet}
{#snippet ring()}〇{/snippet}

<div>
    <Switch aria-label="带开关文字的开关" checkedText={on} uncheckedText={off} />
    <Switch aria-label="带符号文字的开关" checkedText={bar} style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="带开关文字的开关，已开启" checked checkedText={on} uncheckedText={off} />
    <Switch aria-label="带符号文字的开关，已开启" checked checkedText={bar} style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="大号带开关文字的开关" checkedText={on} size="large" uncheckedText={off} />
    <Switch aria-label="大号带符号文字的开关" checkedText={bar} size="large" style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="大号带开关文字的开关，已开启" checked checkedText={on} size="large" uncheckedText={off} />
    <Switch aria-label="大号带符号文字的开关，已开启" checked checkedText={bar} size="large" style="margin-left: 5px" uncheckedText={ring} />
</div>

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

    已关闭
    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';

    let open = $state<boolean>();
</script>

<div style="display: flex; align-items: center">
    <span style="margin: 8px; font-weight: 600">{open ? '已开启' : '已关闭'}</span>
    <Switch aria-label="示例开关" bind:checked={open} />
</div>

    Controlled component

    Use bind:checked to keep the checked state in sync with a $state variable. To reject or rewrite a toggle, use a function binding bind:checked={() => value, (next) => { ... }}; the switch shows what the getter returns. A plain checked without a binding is only the initial value: a click toggles it inside the component, and a new value from the parent wins again.

    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';

    let checked = $state(true);
</script>

<Switch aria-label="受控开关" bind:checked />

    loading

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


    Code
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Switch aria-label="加载中的开关" loading />
    <br />
    <Switch aria-label="加载中的开关，已开启" checked loading />
</div>

    API reference

    Props

    PropertyDescriptionTypeDefault
    checkedChecked state; bind it with bind:checked. bind:checked={get, set} makes it fully controlled; a plain checked is the initial value, a click overrides it inside the component, and a new value from the parent wins again.boolean-
    checkedTextSnippet shown when checked. Not shown when size is small.Snippet-
    disabledWhether the switch is disabled.booleanfalse
    loadingWhether the switch is loading. While loading, the input stays focusable with aria-disabled; toggles are ignored and onChange is not called.booleanfalse
    onChangeCalled when the user toggles the switch, with the new checked state and the native change event. Not called while loading.Type(checked: boolean, event: Event) => void-
    sizeSwitch size: large, default or small.Size"default"
    uncheckedTextSnippet shown when unchecked. Not shown when size is small.Snippet-

    class, style and other native attributes and listeners (such as onmouseenter) land on the root element. id, name, tabindex, autofocus, aria-*, and onfocus and onblur 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.
    • It is recommended to use aria-label to describe the current label function, or aria-labelledby to point to a visible label on the page.

    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 variableValueUsage
    $transition_duration-switch-bg200ms开关-背景色-动画持续时间
    $transition_function-switch-bgvar(--semi-transition_function-easeIn)开关-背景色-过渡曲线
    $transition_delay-switch-bgvar(--semi-transition_delay-none)开关-背景色-延迟时间
    $spacing-switch_unchecked-translateX2px未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked-translateX2px未选中态加载图标位移距离
    $spacing-switch_checked-translateX18px选中态开关滑块位移距离
    $spacing-switch_spin_checked-translateX16px选中态加载图标位移距离
    $spacing-switch_expand_large-translateX10px
    $spacing-switch_unchecked_large-translateX3px大尺寸未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked_large-translateX2px大尺寸未选中态加载图标位移距离
    $spacing-switch_checked_large-translateX26px大尺寸选中态开关滑块位移距离
    $spacing-switch_spin_checked_large-translateX22px大尺寸选中态加载图标位移距离
    $spacing-switch_expand_small-translateX2px
    $spacing-switch_unchecked_small-translateX1px小尺寸未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked_small-translateX2px小尺寸未选中态加载图标位移距离
    $spacing-switch_checked_small-translateX11px小尺寸选中态开关滑块位移距离
    $spacing-switch_spin_checked_small-translateX10px小尺寸选中态加载图标位移距离
    $motion-switch-transitionDuration200ms开关动画时长
    $color-switch_default-bg-defaultvar(--semi-color-fill-0)关闭态(未选中)开关背景色 - 默认
    $color-switch_default-bg-hovervar(--semi-color-fill-1)关闭态开关背景色 - 悬浮
    $color-switch_default-bg-activevar(--semi-color-fill-2)关闭态开关背景色 - 按下
    $color-switch_default-border-defaulttransparent关闭态开关描边颜色
    $color-switch_checked-bg-defaultvar(--semi-color-success)开启态开关背景色 - 默认
    $color-switch_checked-bg-hovervar(--semi-color-success-hover)开启态开关背景色 - 悬浮
    $color-switch_checked-bg-activevar(--semi-color-success-active)开启态开关背景色 - 按下
    $color-switch_disabled-bg-defaulttransparent禁用态开关背景色
    $color-switch_disabled-bg-hovertransparent禁用态开关背景色 - 悬浮
    $color-switch_disabled-bg-activetransparent禁用态开关背景色 - 按下
    $color-switch_disabled-border-defaultvar(--semi-color-border)禁用态开关描边颜色
    $color-switch_disabled-bg-hovertransparent禁用态开关背景色 - 悬浮
    $color-switch_checked_disabled-bg-defaultvar(--semi-color-success-disabled)禁用开启态开关背景颜色
    $color-switch_checked_disabled-border-defaulttransparent禁用开启态开关描边颜色
    $color-switch_knob-bg-defaultvar(--semi-white)开关滑块背景颜色 - 关闭态
    $color-switch_knob-bg-checkedvar(--semi-white)开关滑块背景颜色 - 开启态
    $color-switch_knob-border-defaultvar(--semi-color-border)开关滑块描边颜色
    $color-switch_checked-text-defaultvar(--semi-color-white)开启态开关文案颜色
    $color-switch_unchecked-text-defaultvar(--semi-color-text-2)关闭态开关文案颜色
    $color-switch_loading_spin-defaultvar(--semi-color-white)加载态开关loading图标颜色
    $color-switch_spin_checked-bg-defaultvar(--semi-color-success-hover)已开启开关加载态loading背景颜色
    $color-switch_spin_unchecked-bg-defaultvar(--semi-color-fill-1)已关闭开关加载态loading背景颜色
    $color-switch_primary-outline-focus$color-focus-ring开关轮廓 - 聚焦
    $width-switch40px开关宽度
    $height-switch24px开关高度
    $width-switch_knob_expand6px开关滑块按压时延展宽度
    $width-switch_knob_default18px开关滑块宽度
    $width-switch_knob_active$width-switch_knob_default + $width-switch_knob_expand开关滑块按下态宽度
    $height-switch_large32px大尺寸开关高度
    $width-switch_large54px大尺寸开关宽度
    $width-switch_knob_large24px大尺寸开关滑块宽度
    $width-switch_knob_large_active$width-switch_knob_large + $spacing-switch_expand_large-translateX大尺寸开关滑块按下态宽度
    $height-switch_small16px小尺寸开关高度
    $width-switch_small26px小尺寸开关宽度
    $width-switch_knob_large_small12px小尺寸开关滑块宽度
    $width-switch_knob_small_active$width-switch_knob_large_small + $spacing-switch_expand_small-translateX小尺寸开关滑块按下态宽度
    $width-switch_knob_disabled-border1px禁用态开关滑块边框宽度
    $width-switch_checked_unchecked_text26px开关文案宽度
    $width-switch_spin-small10px小尺寸开关加载 spin 宽度
    $width-switch_spin-default18px默认尺寸开关加载 spin 宽度
    $width-switch_spin-large28px大尺寸开关加载 spin 宽度
    $width-switch-outline$width-focus-ring开关轮廓宽度
    $spacing-switch_knob-padding2px开关滑块顶部边距
    $spacing-switch_knob_large-padding3px大尺寸开关滑块顶部边距
    $spacing-switch_knob_small-padding1px小尺寸开关滑块顶部边距
    $spacing-switch_knob-left0px开关滑块左侧偏移距离
    $radius-switch$height-switch * 0.5开关圆角
    $radius-switch_large$height-switch_large * 0.5大尺寸开关圆角
    $radius-switch_small$height-switch_small * 0.5小尺寸开关圆角