Switch

17:06

Description

A two-state switch; tapping toggles between active-value and inactive-value, synced through v-model. The track is a 50:28 capsule with no border, and the white knob is inset on all sides and always vertically centered; size only describes the track height — track width, inset and knob diameter are derived proportionally.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported (vibrate-short haptic feedback works on this platform only)

Examples

Basic Usage

Bind the switch state with v-model, true/false by default.

View source

<template>
    <ux-switch v-model="value" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

Custom Values

Customize the switch values with active-value and inactive-value.

View source

<template>
    <ux-switch v-model="value" :active-value="100" :inactive-value="1" />
    <text>当前值: {{ value }}</text>
</template>

<script setup lang="uts">
const value = ref<number>(1);
</script>

Color (active-color)

Set the background color when active via active-color.

View source

<template>
    <ux-switch v-model="value" active-color="#19be6b" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

Size (size)

Supports small(22px), default(28px), large(34px) presets and custom values (track height).

View source

<template>
    <ux-switch v-model="value" size="large" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

Loading (loading)

When loading=true the loading animation is shown and the switch is not operable.

View source

<template>
    <ux-switch v-model="value" :loading="true" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

Disabled (disabled)

When disabled=true the switch is not operable and shown semi-transparent.

View source

<template>
    <ux-switch v-model="value" :disabled="true" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
loading	Whether to show the loading state	boolean	false	-
disabled	Whether disabled	boolean	false	-
size	Switch size (track height): small – 22px, default – 28px, large – 34px, or a custom value (in px)	string | number	''	-
activeColor	Color when on	string	''	-
inactiveColor	Color when off	string	''	-
modelValue	v-model bound value; the switch state value	boolean | number | string	false	-
vibrateShort	Whether to enable light haptic feedback	boolean	false	-
activeValue	Value when on	boolean | number | string	true	-
inactiveValue	Value when off	boolean | number | string	false	-
validateState	Whether in a validation error state	boolean	false	-

Events

Event	Description	Params	Version
change	Fires when the switch is turned on or off	value: boolean | number | string	-

Slots

ux-switch has no slots.

Notes

• vibrate-short haptic feedback only works on WeChat Mini Program; it has no effect on App (HBuilderX 2.6.8) or H5.
• The switch state is determined by model-value === active-value; active-value / inactive-value accept boolean, number and string, and must match the type of the bound value.
• Taps are intercepted while loading or disabled, so change is not emitted; change is emitted inside nextTick (waiting for the parent state to sync).
• A non-preset size is used as a custom track height (px): the track width follows 50:28 and the inset 3:28, with knob diameter = track height − 2 × inset.
• disabled sets the whole switch to opacity: 0.6; validate-state or a failed form validation adds a 1px red border on the track.
• The component can inject the ux-form-item context and triggers its validation after toggling.