Slider

A customizable input that allows users to select numeric values by dragging a thumb along a track.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root class="slider-root">
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb class="slider-thumb" />
      </Slider.Track>
    </Slider.Root>
  );
});

Features

WAI ARIA Slider design pattern
Single and range value modes
Customizable step increments
Keyboard navigation with arrow keys
Touch/mouse dragging with pointer events
Shift key for fine-grained control (10x step)
Custom markers/ticks support
Visual range indicator
Home/End key value jumps
Multiple thumb position tracking
Configurable min/max bounds
Custom styling via data attributes
Disabled state handling
Change and change-end event handlers

Anatomy

Part	Description
<Slider.Root>	Root component that provides slider context and handles core slider functionality
<Slider.Track>	Component that renders the track along which the thumb slides
<Slider.Range>	Component that displays the filled range between min value and current value
<Slider.Thumb>	Draggable thumb component that users interact with to change slider values
<Slider.MarkerGroup>	A container component for slider markers
<Slider.Marker>	A marker component that displays a specific value point on the slider

Examples

Basic Usage

The most basic slider implementation allows users to select a single value within a range.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root class="slider-root" value={50} min={0} max={100} step={1}>
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb class="slider-thumb" />
      </Slider.Track>
    </Slider.Root>
  );
});

The min and max props define the range (defaulting to 0-100), while step controls the increment size (default 1). The value prop sets the initial position.

Visual Features

Custom Styling

The slider can be visually customized through CSS classes and inline styles.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root class="slider-root" value={50} min={0} max={100} step={1}>
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb
          class="slider-thumb"
          style={{
            backgroundColor: "red",
            width: "24px",
            height: "24px",
            border: "3px solid darkred"
          }}
        />
      </Slider.Track>
    </Slider.Root>
  );
});

In this example, we customize the thumb's appearance using inline styles, demonstrating how to modify its backgroundColor, width, height, and border.

Markers and Labels

Add visual markers and labels to indicate specific values along the track.

Very Low

Low

Medium

High

Higher

Top

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root class="slider-root" value={50} min={0} max={100} step={20}>
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb class="slider-thumb" />
      </Slider.Track>
      <Slider.MarkerGroup class="slider-marker-group">
        <Slider.Marker value={0} class="slider-marker">
          <span class="slider-mark-label">Very Low</span>
        </Slider.Marker>
        <Slider.Marker value={20} class="slider-marker">
          <span class="slider-mark-label">Low</span>
        </Slider.Marker>
        <Slider.Marker value={40} class="slider-marker">
          <span class="slider-mark-label">Medium</span>
        </Slider.Marker>
        <Slider.Marker value={60} class="slider-marker">
          <span class="slider-mark-label">High</span>
        </Slider.Marker>
        <Slider.Marker value={80} class="slider-marker">
          <span class="slider-mark-label">Higher</span>
        </Slider.Marker>
        <Slider.Marker value={100} class="slider-marker">
          <span class="slider-mark-label">Top</span>
        </Slider.Marker>
      </Slider.MarkerGroup>
    </Slider.Root>
  );
});

The <Slider.MarkerGroup> component contains <Slider.Marker> elements, each with a value prop that determines its position. Labels can be added as children.

Advanced Usage

Range Selection

Create a range slider with two thumbs for selecting a value range.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root class="slider-root" isRange value={[30, 70]} min={0} max={100} step={1}>
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb type="start" class="slider-thumb" />
        <Slider.Thumb type="end" class="slider-thumb" />
      </Slider.Track>
    </Slider.Root>
  );
});

Set isRange to true and provide an array of two values [start, end] to create a range slider.

Range with Markers

Combine range selection with markers for a more informative interface.

25%

50%

75%

100%

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root
      class="slider-root"
      isRange
      value={[25, 75]}
      min={0}
      max={100}
      step={25}
      onChange$={(values: number | [number, number]) => {
        console.log("Values changed:", values);
      }}
      onChangeEnd$={(values) => {
        console.log("Final values:", values);
      }}
    >
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb type="start" class="slider-thumb" />
        <Slider.Thumb type="end" class="slider-thumb" />
      </Slider.Track>
      <Slider.MarkerGroup class="slider-marker-group">
        <Slider.Marker value={0}>0%</Slider.Marker>
        <Slider.Marker value={25}>25%</Slider.Marker>
        <Slider.Marker value={50}>50%</Slider.Marker>
        <Slider.Marker value={75}>75%</Slider.Marker>
        <Slider.Marker value={100}>100%</Slider.Marker>
      </Slider.MarkerGroup>
    </Slider.Root>
  );
});

This example shows how to integrate markers with a range slider, providing visual reference points for both thumbs.

Callbacks

Track value changes and final selections with callback functions.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  return (
    <Slider.Root
      class="slider-root"
      onChange$={(value: number | [number, number]) => {
        console.log("Value changed:", value);
      }}
      onChangeEnd$={(value) => {
        console.log("Final value:", value);
      }}
    >
      <Slider.Track class="slider-track">
        <Slider.Range class="slider-range" />
        <Slider.Thumb class="slider-thumb" />
      </Slider.Track>
    </Slider.Root>
  );
});

The onChange$ prop fires on every value change, while onChangeEnd$ fires when the user finishes dragging or keyboard navigation.

Disabled State

Control the slider's interactive state.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Slider } from "@kunai-consulting/qwik";
import styles from "./slider-custom.css?inline";

export default component$(() => {
  useStyles$(styles);
  const isDisabled = useSignal(true);

  return (
    <div>
      <Slider.Root
        class="slider-root"
        value={50}
        min={0}
        max={100}
        step={1}
        disabled={isDisabled}
        onChange$={(value: number | [number, number]) => {
          console.log("This should not be called when disabled:", value);
        }}
      >
        <Slider.Track class="slider-track">
          <Slider.Range class="slider-range" />
          <Slider.Thumb class="slider-thumb" />
        </Slider.Track>
      </Slider.Root>
      <button
        type="button"
        onClick$={() => {
          isDisabled.value = !isDisabled.value;
        }}
      >
        Toggle Disabled
      </button>
    </div>
  );
});

The disabled prop can be a boolean or signal to toggle the slider's interactive state. When disabled, all interactions are prevented.

Component State

Using Component State

The Slider component offers flexible state management through its props. Here are the key ways to control the slider's state:

Single Value Mode As shown in the "single-default-values" example above, you can control the slider's value using the value prop. The slider accepts a number between the min and max values.
Range Mode To enable range selection mode, set the isRange prop to true and provide an array of two numbers as the value prop, representing the start and end values. This is demonstrated in the "range" example above.
Bounds and Steps Control the slider's range and granularity with:

min: Set the minimum value (defaults to 0)
max: Set the maximum value (defaults to 100)
step: Define the increment size (defaults to 1)

Disabled State As shown in the "disabled" example above, you can disable the slider by setting the disabled prop to true. This prevents all user interactions with the slider.

State Interactions

The Slider component provides two main ways to respond to state changes:

Value Changes Use the onChange$ prop to handle immediate value changes:

<Slider.Root
  onChange$={(value) => {
    console.log('Value changed:', value);
  }}
>

Committed Values The onChangeEnd$ prop is called when the user finishes interacting with the slider (after drag or keyboard navigation):

<Slider.Root
  onChangeEnd$={(value) => {
    console.log('Final value:', value);
  }}
>

As shown in the "callbacks" example above, both handlers receive either:

A single number in single-value mode
An array of two numbers [start, end] in range mode These handlers are useful for:
Updating external state
Triggering side effects
Validating values
Synchronizing with other components The state management system ensures that:
Values stay within the defined min and max bounds
Range values maintain their order (start ≤ end)
Values snap to the nearest step
The UI updates smoothly during interactions

Based on the provided implementation and examples, I'll document the configuration options for the Slider component.

Core Configuration

Value and Range Mode

The Slider can be configured in two modes: single value or range. The core configuration is handled through the SliderRoot component. As shown in the hero example above, a basic single-value slider can be created with minimal configuration. By default, it operates with:

min: 0
max: 100
step: 1
value: 0 (single mode) or [0, 100] (range mode) For range mode, as demonstrated in the range example, set isRange to true and provide an array of two values:

type SliderValue = number | [number, number];

Step Configuration

The slider supports custom step intervals through the step prop. As shown in the marks example above, you can configure larger step intervals to create discrete value points.

The step value must be greater than 0 and should evenly divide into the range between min and max for optimal behavior.

Marker System

The Slider supports a marker system for displaying value points along the track. As shown in the range-marks example above, markers can be added with labels to create a more informative slider. Markers must have values within the slider's min/max range and are positioned automatically based on the percentage calculation:

markerPosition = ((value - min) / (max - min)) * 100

Advanced Configuration

Value Updates and Callbacks

The Slider provides two callback mechanisms:

onChange$: Fires during continuous value changes (dragging)
onChangeEnd$: Fires when value changes are committed As shown in the callbacks example above, these can be used to track both intermediate and final values.

Disabled State Management

The disabled state can be controlled either through a boolean or a signal. As shown in the disabled example above, the slider supports dynamic toggling of the disabled state. When disabled:

All user interactions are prevented
Callbacks are not fired
ARIA attributes are automatically updated
Visual styling can be controlled via the aria-disabled attribute

API Reference

Slider Root

Inherits from: <div />

Props

Prop	Type	Default
isRange	boolean	false
value	SliderValue \| Signal<SliderValue>	isRange ? [0, 100] : 0
min	number	0
max	number	100
step	number	1
disabled	boolean \| Signal<boolean>	false
onChange$	\| QRL<(value: SliderValue) => void> \| PropFunction<(value: SliderValue) => void>	-
onChangeEnd$	\| QRL<(value: SliderValue) => void> \| PropFunction<(value: SliderValue) => void>	-

Slider Thumb

Data Attributes

Attribute	Description
data-thumb-type	Identifies whether the thumb is for the start or end value in range mode

Slider Marker Group

Inherits from: <div />

Slider Range

Inherits from: <div />

Slider Track

Inherits from: <div />