Slider

Slider is an unstyled slider for one value or multiple thumbs. It renders a track, filled range, and role="slider" thumbs with pointer dragging, keyboard stepping, hidden form input support, and CSS variables for styling.

Use Slider for pointer-based range input. Use Number Field for exact typed values.

Load the required structural CSS before using Slider. The examples below use Tailwind for visual styling; the ui prop does not load either stylesheet.

Anatomy

• #range: Custom content inside the filled range.
• #thumb: Custom content inside each focusable role="slider" thumb.

The root, hidden inputs, track, range, and thumbs are generated by the component. The root sets --akaza-slider-percentage, --akaza-slider-start-percentage, and --akaza-slider-end-percentage for styling.

Usage

<script setup lang="ts">
import { Slider } from "akaza-ui";
import { ref } from "vue";

const volume = ref(60);
</script>

<template>
  <Slider
    v-model="volume"
    aria-label="Volume"
    :ui="{
      root: 'h-6 w-full max-w-xs',
      track: 'h-2 w-full rounded-full bg-neutral-200 dark:bg-neutral-800',
      range: 'h-full rounded-full bg-neutral-900 dark:bg-white',
      thumb: 'size-5 rounded-full border-2 border-neutral-900 bg-white outline-none focus-visible:ring-2 focus-visible:ring-neutral-900 dark:border-white dark:bg-neutral-950 dark:focus-visible:ring-white',
    }"
  />
</template>

Examples

Range slider

Bind v-model to a number array. Provide aria-labels so each thumb has a clear accessible name.

<script setup lang="ts">
import { ref } from "vue";
import { Slider } from "akaza-ui";

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

<template>
  <Slider
    v-model="price"
    :min="0"
    :max="100"
    :step="5"
    :aria-labels="['Minimum price', 'Maximum price']"
  />
</template>

Minimum distance between thumbs

minStepsBetweenThumbs keeps adjacent thumbs apart by step units.

<template>
  <Slider v-model="range" :step="5" :min-steps-between-thumbs="2" />
</template>

Vertical slider

Use orientation="vertical" and give the root a height. Style the track, range, and thumb as well: the vertical range needs a width, and the thumb needs explicit dimensions. Values increase from bottom to top.

<script setup lang="ts">
import { Slider } from "akaza-ui";
import { ref } from "vue";

const volume = ref(60);
</script>

<template>
  <div class="flex items-center gap-4">
    <Slider
      v-model="volume"
      orientation="vertical"
      aria-label="Volume"
      :ui="{
        root: 'h-40 w-6',
        track: 'h-full w-2 rounded-full bg-neutral-200 dark:bg-neutral-800',
        range: 'w-full rounded-full bg-neutral-900 dark:bg-white',
        thumb: 'size-5 rounded-full border-2 border-neutral-900 bg-white outline-none focus-visible:ring-2 focus-visible:ring-neutral-900 dark:border-white dark:bg-neutral-950 dark:focus-visible:ring-white',
      }"
    />
    <span class="text-sm tabular-nums">Volume: {{ volume }}</span>
  </div>
</template>

Troubleshooting: a horizontal native slider appears

Slider renders a native <input type="range"> for form integration and custom thumbs for interaction. Package CSS hides the native input and positions the custom parts. If a browser-default horizontal slider appears, check that akaza-ui/dist/akaza-ui.css is loaded and that your CSS has not overridden .akaza-slider-input visibility or positioning. The native input's horizontal behavior can conflict with the component's vertical pointer calculations when it is visible.

With Tailwind, import the stylesheet in your CSS entry after Tailwind, keeping the layer declaration first:

@layer akaza-reset;
@import "tailwindcss";
@import "akaza-ui/dist/akaza-ui.css";

Without Tailwind, import akaza-ui/dist/akaza-ui.css once from main.ts. The Nuxt module injects this stylesheet automatically. Without it, orientation="vertical" still updates ARIA and pointer calculations, but cannot supply the CSS layout. If the stylesheet is loaded and the slider is blank, check that Tailwind generated your ui classes and that track colors, range width, and thumb dimensions are set.

Inverted direction

inverted reverses pointer and keyboard value direction.

<template>
  <Slider v-model="brightness" inverted aria-label="Brightness" />
</template>

Custom thumb content

Use #thumb when the thumb needs visible value text or custom markup.

<template>
  <Slider v-model="value" aria-label="Progress">
    <template #thumb="{ value }">
      <span>{{ value }}</span>
    </template>
  </Slider>
</template>

Range accessibility and forms

Every thumb has a unique id: the first uses id (or the generated Field id); later thumbs append -2, -3, and so on. Use ariaLabels for distinct endpoint names. Each thumb reports bounds constrained by its neighbors and minStepsBetweenThumbs.

Disabling the slider disables all serialization inputs, including each range value. Native disabled fieldsets also block pointer/keyboard changes. Visual track thickness, thumb size, colors, and focus rings belong in ui.

Native Form Reset

A native form reset restores the initial model and clears interaction state. Calling preventDefault() on the reset event preserves the current value. Reset updates v-model without emitting value-change.

API Reference

Props

Emits

Slots

UI Options

Styling Hooks

Slider sets --akaza-slider-percentage, --akaza-slider-start-percentage, and --akaza-slider-end-percentage on the root. Plain class applies to the root wrapper.

Native invalid state from the hidden form input is revealed after interaction or invalid submit. Controlled invalid state from the invalid prop or parent Field appears immediately.

Keyboard