Slider

Overview

VySlider is a themed wrapper around the @vyui/core slider primitives. It supports a single numeric value or multiple thumbs, horizontal and vertical tracks, step snapping, minimum thumb spacing, inversion, semantic colors, and controlled or uncontrolled state.

Usage

<script setup lang="ts">
import { ref } from 'vue'
import { VySlider } from '@vyui/kit'

const volume = ref(40)
</script>

<template>
  <VySlider v-model="volume" :min="0" :max="100" />
</template>

The shape of the bound value is preserved: a number emits a number, while an array emits an array.

Range

Use an array to render one thumb per value.

<script setup lang="ts">
import { ref } from 'vue'
import { VySlider } from '@vyui/kit'

const price = ref([20, 80])
</script>

<template>
  <VySlider
    v-model="price"
    :min="0"
    :max="100"
    :step="5"
    :min-steps-between-thumbs="2"
    color="success"
  />
</template>

minStepsBetweenThumbs is measured in steps. With step="5" and minStepsBetweenThumbs="2", adjacent thumbs remain at least 10 units apart.

Vertical

A vertical slider needs an explicit height from its parent or class.

<template>
  <VySlider
    :default-value="60"
    orientation="vertical"
    class="h-48"
  />
</template>

Features and behavior

• modelValue controls the slider; defaultValue initializes uncontrolled state.
• A number creates one thumb. An array creates one thumb for every entry.
• Values are clamped to min and max, snapped to step, and kept in ascending order.
• inverted reverses the visual value direction. A normal vertical slider runs from minimum at the bottom to maximum at the top.
• Tapping or dragging the track moves the closest thumb.
• disabled prevents interaction and dims the root.
• The kit wrapper does not expose the core slider's valueCommit event.

Props

Color defaults to primary, secondary, success, info, warning, error, or neutral, and supports registry extensions.

Emits

Slots

This kit component does not expose slots. Use the ui prop to customize its rendered parts, or compose the headless slider primitives from @vyui/core when custom markup is required.

Styling and theming

Override globally through appConfig.ui.slider or locally with ui.

The color variant colors the range and thumb border. The size variant changes the thumb from 16px to 24px and adjusts track thickness. Orientation switches the root and range axes.

Accessibility

Each core thumb is an adjustable accessibility element and announces its current value as “value of maximum.” A two-thumb slider labels its thumbs “Minimum” and “Maximum”; larger ranges use numbered value labels. Pair the slider with nearby visible text that explains what the value controls, and show the current value separately when users need exact feedback.

The kit wrapper does not currently expose per-thumb slots or a direct per-thumb accessibility-label API. Use the @vyui/core primitives when each thumb requires a custom accessible name.

Platform notes

• Dragging uses Lynx touch events rather than DOM pointer events.
• The core control uses a main-thread drag path by default for smooth native movement. The bound value is synchronized when the gesture commits rather than on every painted frame.
• Thumb positions use concrete inline transforms because Lynx native does not resolve inline CSS custom properties reliably.
• Vertical sliders require a constrained height; horizontal sliders fill the available width by default.

Related components

• Progress for displaying a non-interactive value.
• NumberField for precise typed increments.
• The @vyui/core slider primitives for custom tracks, ranges, and thumbs.