Input · Switch

Switch

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

Demos

How to import

<script setup lang="ts">
    import { Switch } from '@fibrous/semi-ui-vue';
</script>

Basic Usage

You can monitor state changes through @change, and set the selected state through defaultChecked or modelValue (v-model).
Use aria-label to describe the specific function of the Switch


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

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

<template>
    <div>
        <Switch aria-label="a switch for demo" @change="log" />
        <br />
        <Switch aria-label="a switch for semi demo" defaultChecked @change="log" />
    </div>
</template>

Size

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

<template>
    <div>
        <Space :style="{ marginBottom: '10px', display: 'block' }">
            <Switch aria-label="a switch for demo" size="small" />
            <Switch aria-label="a switch for demo" defaultChecked size="small" />
            <Switch aria-label="a switch for demo" loading size="small" />
            <Switch aria-label="a switch for demo" defaultChecked loading size="small" />
        </Space>
        <Space :style="{ marginBottom: '10px', display: 'block' }">
            <Switch aria-label="a switch for demo" />
            <Switch aria-label="a switch for demo" defaultChecked />
            <Switch aria-label="a switch for demo" loading />
            <Switch aria-label="a switch for demo" defaultChecked loading />
        </Space>
        <Space>
            <Switch aria-label="a switch for demo" size="large" />
            <Switch aria-label="a switch for demo" defaultChecked size="large" />
            <Switch aria-label="a switch for demo" loading size="large" />
            <Switch aria-label="a switch for demo" defaultChecked loading size="large" />
        </Space>
    </div>
</template>

Disabled


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

<template>
    <div>
        <Switch aria-label="a switch for demo" disabled />
        <br />
        <Switch aria-label="a switch for demo" disabled modelValue />
    </div>
</template>

With text

Can pass the #checkedText and #uncheckedText slots to set the text of 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
<script setup lang="ts">
    import { Switch } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Switch aria-label="带开关文字的开关">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="带符号文字的开关" :style="{ marginLeft: '5px' }">
            <template #checkedText>|</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="带开关文字的开关,已开启" defaultChecked>
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="带符号文字的开关,已开启" defaultChecked :style="{ marginLeft: '5px' }">
            <template #checkedText>|</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="大号带开关文字的开关" size="large">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="大号带符号文字的开关" size="large" :style="{ marginLeft: '5px' }">
            <template #checkedText>|</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="大号带开关文字的开关,已开启" defaultChecked size="large">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="大号带符号文字的开关,已开启" defaultChecked size="large" :style="{ marginLeft: '5px' }">
            <template #checkedText>|</template>
            <template #uncheckedText>〇</template>
        </Switch>
    </div>
</template>

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

已关闭
Code
<script setup lang="ts">
    import { ref } from 'vue';
    import { Switch, Typography } from '@fibrous/semi-ui-vue';

    const { Title } = Typography;
    const open = ref<boolean>();
</script>

<template>
    <div :style="{ display: 'flex', alignItems: 'center' }">
        <Title :heading="6" :style="{ margin: '8px' }">{{ open ? '已开启' : '已关闭' }}</Title>
        <Switch v-model="open" aria-label="a switch for demo" />
    </div>
</template>

Controlled component

Whether the component is selected depends entirely on the incoming modelValue, used with v-model. With a one-way :modelValue and no write-back, a click only notifies and the passed value decides what is shown.

Code
<script setup lang="ts">
    import { ref } from 'vue';
    import { Switch } from '@fibrous/semi-ui-vue';

    const checked = ref(true);
</script>

<template>
    <Switch v-model="checked" aria-label="a switch for demo" />
</template>

loading

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


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

<template>
    <div>
        <Switch aria-label="Loading switch" loading />
        <br />
        <Switch aria-label="Loading switch, on" defaultChecked loading />
    </div>
</template>

API reference

Props

PropertyDescriptionTypeDefault
modelValueWhether the switch is on, used with v-model. When given, this value decides; without a write-back, a click only notifies.booleanundefined
defaultCheckedInitial state when uncontrolled.booleansemiGlobalDefault("Switch", "defaultChecked")
disabledWhether the switch is disabled.booleansemiDefault("Switch", "disabled", false)
loadingWhether the switch is loading. While loading, the input stays focusable with aria-disabled, and toggles are ignored without emitting events.booleansemiDefault("Switch", "loading", false)
sizeSwitch size: large, default or small.SizesemiDefault("Switch", "size", "default")

Events

EventDescriptionCallback parameters
update:modelValueEmitted when the user toggles the switch, for v-model to write back.[checked: boolean]
changeEmitted when the user toggles the switch, with the new state and the native event.[checked: boolean, event: Event]

Slots

SlotDescriptionScope parameters
checkedTextContent shown when on. Not shown when size is small.any
uncheckedTextContent shown when off. Not shown when size is small.any

Exposes

NameDescriptionType
None

class and style land on the root element. id, name, tabindex, autofocus, aria-* and focus and blur listeners passed as attrs land on the inner native input; other native attributes and listeners (such as @mouseenter) land on the root element.

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小尺寸开关圆角