Switch

Switch is used for switching between two opposing states.

Basic usage

Bind v-model to a Boolean typed variable. The --el-switch-on-color and --el-switch-off-color CSS variables decides the background color in two states.

---

<template>
  <b-switch v-model="value1" />
  <b-switch
    v-model="value2"
    class="ml-2"
    style="--b-switch-on-color: #13ce66; --b-switch-off-color: #ff4949"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref(true)
const value2 = ref(true)
</script>

Sizes

Close

Open

Close

Open

Close

Open

---

<template>
  <b-space vertical alignment="flex-start">
    <b-switch v-model="value" large active-text="Open" inactive-text="Close" />
    <b-switch v-model="value" active-text="Open" inactive-text="Close" />
    <b-switch v-model="value" small active-text="Open" inactive-text="Close" />
  </b-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref(true)
</script>

Text description

You can add active-text and inactive-text attribute to show texts. use inline-prompt attribute to control text is displayed inside dot.

You can add active-text and inactive-text attribute to show texts.

Pay by year

Pay by month

YN

---

<template>
  <b-switch
    v-model="value"
    class="mb-2"
    active-text="Pay by month"
    inactive-text="Pay by year"
  />
  <br />
  <b-switch v-model="value" inline-prompt active-text="Y" inactive-text="N" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref(true)
</script>

Display custom icons

TIP

Use the active-icon and inactive-icon attribute to add icon. You can pass either string for the component name (registered in advance) or the component itself which is a SVG Vue component. Element Plus has provided a set of icon that you can find at icon

You can add active-icon and inactive-icon attribute to show icons. use inline-prompt attribute to control icon is displayed inside dot.

---

<template>
  <b-space>
    <b-switch v-model="value1" :active-icon="Check" :inactive-icon="Close" />
    <b-switch
      v-model="value2"
      inline-prompt
      :active-icon="Check"
      :inactive-icon="Close"
    />
  </b-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Check, Close } from '@bigin/icons-vue'
const value1 = ref(true)
const value2 = ref(true)
</script>

Extended value types

You can set active-value and inactive-value attributes. They both receive a Boolean, String or Number typed value.

---

<template>
  <b-tooltip :content="'Switch value: ' + value" placement="top">
    <b-switch v-model="value" active-value="100" inactive-value="0" />
  </b-tooltip>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('100')
</script>

Disabled

Adding the disabled attribute disables Switch.

---

<template>
  <b-switch v-model="value1" disabled />
  <b-switch v-model="value2" class="ml-2" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref(true)
const value2 = ref(true)
</script>

Loading

Setting the loading attribute to true indicates a loading state on the Switch.

---

<template>
  <b-switch v-model="value1" loading />
  <b-switch v-model="value2" loading class="ml-2" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref(true)
const value2 = ref(false)
</script>

Prevent switching

set the before-change property, If false is returned or a Promise is returned and then is rejected, will stop switching.

---

<template>
  <b-switch
    v-model="value1"
    :loading="loading1"
    :before-change="beforeChange1"
  />
  <b-switch
    v-model="value2"
    class="ml-2"
    :loading="loading2"
    :before-change="beforeChange2"
  />
</template>
<script lang="ts" setup>
import { ref } from 'vue'
import { BMessage } from 'bigin-ui'

const value1 = ref(false)
const value2 = ref(false)
const loading1 = ref(false)
const loading2 = ref(false)

const beforeChange1 = () => {
  loading1.value = true
  return new Promise((resolve) => {
    setTimeout(() => {
      loading1.value = false
      BMessage.success('Switch success')
      return resolve(true)
    }, 500)
  })
}

const beforeChange2 = () => {
  loading2.value = true
  return new Promise((_, reject) => {
    setTimeout(() => {
      loading2.value = false
      BMessage.error('Switch failed')
      return reject(new Error('Error'))
    }, 500)
  })
}
</script>

Attributes

Name	Description	Type	Accepted Values	Default
model-value / v-model	binding value, it should be equivalent to either active-value or inactive-value, by default it's boolean type	boolean / string / number	—	—
disabled	whether Switch is disabled	boolean	—	false
loading	whether Switch is in loading state	boolean	—	false
size	size of Switch	string	large / default / small	default
width	width of Switch	number / string	—	—
inline-prompt	whether icon or text is displayed inside dot, only the first character will be rendered for text	boolean	—	false
active-icon	component of the icon displayed when in on state, overrides active-text	string | Component	—	—
inactive-icon	component of the icon displayed when in off state, overrides inactive-text	string | Component	—	—
active-text	text displayed when in on state	string	—	—
inactive-text	text displayed when in off state	string	—	—
active-value	switch value when in on state	boolean / string / number	—	true
inactive-value	switch value when in off state	boolean / string / number	—	false
active-color	background color when in on state ( deprecated, use CSS var --b-switch-on-color instead )	string	—	—
inactive-color	background color when in off state ( deprecated, use CSS var --b-switch-off-color instead )	string	—	—
border-color	border color of the switch ( deprecated, use CSS var --b-switch-border-color instead )	string	—	—
name	input name of Switch	string	—	—
validate-event	whether to trigger form validation	boolean	—	true
before-change	before-change hook before the switch state changes. If false is returned or a Promise is returned and then is rejected, will stop switching	() => Promise<boolean> | boolean	—	—

Events

Name	Description	Parameters
change	triggers when value changes	value after changing

Methods

Method	Description	Parameters
focus	focus the Switch component	—