Slider

17:06

Description

Drags to select a value within start–end, two-way bound via v-model, with step controlling the increment and min / max further restricting the draggable range. Optionally shows the current value (show-value, positioned by value-position) and the two edge values (show-edge-value); the thumb provides a default slot for custom content.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Bind value via v-model; drag the thumb or tap the bar to change.

View source

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

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

Custom Range

Set range via start/end, step via step; here -50 to 50 with step 5.

View source

<template>
    <ux-slider v-model="value" :start="-50" :end="50" :step="5" />
</template>

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

Show Value

When show-value=true, display the current value above the thumb.

View source

<template>
    <ux-slider v-model="value" :show-value="true" />
</template>

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

Value & Edge Positions

value-position moves the current value below the track; show-edge-value=true prints the start/end values at both ends. These labels are out of flow, so the component reserves the space for them and they never overlap neighbouring elements.

View source

<template>
    <ux-slider v-model="value1" :show-value="true" value-position="bottom" />
    <ux-slider v-model="value2" custom-class="slider-gap" :show-value="true" :show-edge-value="true" edge-value-position="top" />
</template>

<script setup lang="uts">
const value1 = ref<number>(35);
const value2 = ref<number>(70);
</script>

<style lang="scss">
.slider-gap {
    margin-top: 20px;
}
</style>

Custom Color

Customize progress bar colors via active-color and inactive-color.

View source

<template>
    <ux-slider v-model="value" active-color="#fa3534" inactive-color="#e4e7ed" />
</template>

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

Disabled

When disabled=true, the slider cannot be dragged.

View source

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

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

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
modelValue	Current value (default 0)	number | string	0	-
start	Start value of the overall range (default 0)	number | string	0	-
end	End value of the overall range (default 50)	number | string	100	-
min	Minimum draggable value (default 0)	number | string	0	-
max	Maximum draggable value (default 50)	number | string	100	-
step	Step size (default 1)	number | string	1	-
blockWidth	Thumb width; height equals width, in px (default 15)	number | string	15	-
height	Track height in px (default 3)	number | string	3	-
activeColor	Color of the active (filled) part of the track	string	''	-
inactiveColor	Background color of the track	string	''	-
blockColor	Thumb color	string	''	-
blockStyle	Custom thumb style	UTSJSONObject	-	-
disabled	Whether the slider is disabled (default false)	boolean	false	-
showValue	Whether to show the current value (default false)	boolean	false	-
valuePosition	Position of the value: top – above, bottom – below (default top)	string	'top'	-
showEdgeValue	Whether to show the start and end values (default false)	boolean	false	-
edgeValuePosition	Position of the start/end values (default top)	string	'top'	-
validateState	Whether in a validation error state (linked from the parent form-item, default false)	boolean	false	-

Events

Event	Description	Params	Version
start	Fires when dragging starts	-	-
moving	Fires continuously while dragging	-	-
end	Fires when dragging ends	-	-

Slots

Slot	Description	Version
default	Custom thumb content (defaults to a white round thumb)	-

Notes

• The effective drag range is decided by min / max together with start / end: min / max are clamped inside start / end.
• The final value is rounded to align with step (Math.round(v / step) * step); a non-positive step is treated as 1.
• The show-value / show-edge-value labels are absolutely positioned and take no in-flow height, so the component reserves space above/below the root (26px each) to avoid overlapping neighbouring elements.
• While dragging, update:modelValue and moving are emitted continuously; start fires when dragging begins and end when it finishes.
• The thumb is square (both width and height use block-width) and supports a default slot for custom content.
• The component can inject the ux-form-item context and triggers its validation after a drag ends or the track is tapped; validate-state adds a red border on the track.