VSwitch

VSwitch wraps Element Plus ElSwitch and adds an awaited on-change callback, optional automatic loading state, and a custom extended switch style enabled by default.

Basic Usage

Use on-change to run side effects after the value changes.

Auto Loading

Keep the switch in loading state while the awaited on-change handler is running.

OFF

Complete example

Combine async state updates, guarded switching with before-change, string-based values, and custom action slots.

Async status sync	Disabled
Guarded release state	P published
Custom action slots	Offline Online online

vue

<template>
  <div class="v-switch-complete">
    <el-descriptions :column="1" border>
      <el-descriptions-item label="Async status sync">
        <div class="row">
          <v-switch
            v-model="enabled"
            :on-change="handleAsyncChange"
            active-text="Enabled"
            inactive-text="Disabled"
          />
          <el-tag :type="enabled ? 'success' : 'info'">
            {{ enabled ? 'Enabled' : 'Disabled' }}
          </el-tag>
        </div>
      </el-descriptions-item>

      <el-descriptions-item label="Guarded release state">
        <div class="row">
          <v-switch
            v-model="releaseState"
            :before-change="beforeReleaseChange"
            active-value="published"
            inactive-value="draft"
            inline-prompt
            active-text="P"
            inactive-text="D"
          />
          <span class="value-text">{{ releaseState }}</span>
        </div>
      </el-descriptions-item>

      <el-descriptions-item label="Custom action slots">
        <div class="row">
          <v-switch v-model="slotValue" :auto-loading="false">
            <template #active>Online</template>
            <template #inactive>Offline</template>
            <template #active-action>
              <Check class="action-icon" />
            </template>
            <template #inactive-action>
              <Close class="action-icon" />
            </template>
          </v-switch>
          <span class="value-text">{{ slotValue ? 'online' : 'offline' }}</span>
        </div>
      </el-descriptions-item>
    </el-descriptions>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { Check, Close } from '@element-plus/icons-vue'

const enabled = ref(false)
const releaseState = ref<'draft' | 'published'>('published')
const slotValue = ref(true)

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

const handleAsyncChange = async (value: boolean) => {
  await sleep(1000)
  ElMessage.success(`Status updated: ${value ? 'enabled' : 'disabled'}`)
}

const beforeReleaseChange = async () => {
  await sleep(600)

  if (releaseState.value === 'draft') {
    ElMessage.warning('Publishing is blocked in this demo')
    return false
  }

  return true
}
</script>

<style scoped>
.v-switch-complete {
  width: 100%;
}

.row {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}

.value-text {
  color: var(--el-text-color-regular);
}

.action-icon {
  width: 12px;
  height: 12px;
}
</style>

Behavior Notes

on-change is a prop callback, not a dedicated emitted event. It receives (value, closeLoading) after the inner switch value changes.
When auto-loading is true by default, VSwitch uses its internal loading state while on-change is running, so the loading prop is ignored.
Call closeLoading() inside on-change if you need to stop the internal loading state before the awaited handler finishes.
When auto-loading is false, use the regular loading prop for manual loading control.
custom-shape is enabled by default and applies the custom extended switch appearance from the theme styles.
Named slots are forwarded to ElSwitch, so active, inactive, active-action, and inactive-action are available.
model-value should match either active-value or inactive-value. If it does not, the underlying switch falls back to inactive-value.

API

VSwitch Attributes

Name	Description	Type	Default
model-value / v-model	switch binding value	`boolean` / `string` / `number`	false
on-change	awaited callback invoked after value change	`function`	—
custom-shape	apply the custom extended switch style	`boolean`	true
auto-loading	automatically manage internal loading state while `on-change` is running	`boolean`	true
disabled	disable the switch	`boolean`	false
loading	manual loading state, used when `auto-loading` is `false`	`boolean`	false
size	switch size	`enum`	—
width	switch width	`number` / `string`	`''`
inline-prompt	show prompt inside the switch	`boolean`	false
active-action-icon	icon for the action area when checked	`string` / `Component`	—
inactive-action-icon	icon for the action area when unchecked	`string` / `Component`	—
active-icon	icon when active, overrides `active-text`	`string` / `Component`	—
inactive-icon	icon when inactive, overrides `inactive-text`	`string` / `Component`	—
active-text	text when active	`string`	''
inactive-text	text when inactive	`string`	''
active-value	value when active	`boolean` / `string` / `number`	true
inactive-value	value when inactive	`boolean` / `string` / `number`	false
name	input name attribute	`string`	''
validate-event	trigger form validation	`boolean`	true
before-change	hook before value change, return `false` or reject to prevent the switch from toggling	`function`	—
id	input id	`string`	—
tabindex	input tabindex	`string` / `number`	—

VSwitch Events

Name	Description	Type
update:model-value	triggered when value changes	`function`

VSwitch Slots

Name	Description
active	content shown for the active state label or prompt
inactive	content shown for the inactive state label or prompt
active-action	content shown inside the action area when checked
inactive-action	content shown inside the action area when unchecked

Source

Docs

VDialog

VInputNumber

VSwitch ​

Basic Usage ​

Auto Loading ​

Complete example ​

Behavior Notes ​

API ​

VSwitch Attributes ​

VSwitch Events ​

VSwitch Slots ​

Source ​