@xsolla/xui-slider

v0.183.0

Published

20 hours ago

A cross-platform React slider component for selecting values within a range. Supports single value, range mode with two thumbs, and optional input fields for direct value entry.  Slider lets users set a value by d

0High
0Medium
0Low

admins-xsolla

Slider

A cross-platform React slider component for selecting values within a range. Supports single value, range mode with two thumbs, and optional input fields for direct value entry.

Slider lets users set a value by dragging a thumb along a track. The filled portion of the track shows the current magnitude, giving immediate visual feedback. With Range: True the slider has two thumbs, letting users define a span between a minimum and a maximum.

When to use

When the user adjusts a value along a continuous or stepped scale and quick, approximate setting matters more than exact entry (volume, brightness, opacity, zoom)

When seeing the magnitude visually helps the user judge the choice
When filtering by a numeric range — use Range: True for a min–max span (e.g. price, age)

When not to use

When the user needs to enter a precise or exact number — use a numeric InputRange field instead

When the choice is a small set of discrete, named options — use a SegmentedControl or Radio buttons instead or MultiSelect

When the control is a simple on/off — use a Switch instead
When the value has no meaningful continuous or ordered scale

Content guidelines

Always pair the slider with a visible label and a readout of the current value; do not rely on the thumb position alone.

Show units in the value readout where relevant (e.g. "70%", "$1,200").

Display the minimum and maximum bounds when they aren't obvious, so users understand the range.

For Range: True, expose both values (lower and upper) so the selected span is always clear.

Keep the scale meaningful: choose a step that matches how precisely the user actually needs to set the value.

Behaviour guidelines

Setting a value — the user drags the thumb or clicks anywhere on the track; the filled portion updates to reflect the current value.

Fullness — the fill grows from the start of the track to the thumb, representing the value from 0 to 100% of the range.

Range: True — two thumbs define the span; the fill sits between them, and the thumbs cannot cross past each other.

Feedback — reflect the current value live while dragging; surface the exact value (e.g. in a tooltip or the readout) so users aren't guessing.

Disabled — the disabled state is dimmed and non-interactive; the thumb cannot be dragged or focused.

Accessibility

Each thumb must be keyboard-operable: arrow keys adjust by one step, and Home / End jump to the minimum and maximum.

Expose the value to assistive technology with the slider role and current, minimum, and maximum values, including a text version with units where needed.

For Range: True, make each thumb separately focusable and clearly labelled (e.g. "Minimum" and "Maximum").

Show a visible focus indicator on the active thumb.

Never rely on the fill color alone to communicate the value — always provide a textual readout and an associated label.

Disabled sliders should not receive keyboard focus; consider a read-only presentation if the value still needs to be conveyed.

Installation

npm install @xsolla/xui-slider

Demo

Basic Slider

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function BasicSlider() {
  const [value, setValue] = React.useState(50);

  return <Slider value={value} onChange={setValue} min={0} max={100} />;
}

Slider with Label

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function SliderWithLabel() {
  const [volume, setVolume] = React.useState(75);

  return (
    <Slider
      value={volume}
      onChange={setVolume}
      min={0}
      max={100}
      label={`Volume: ${volume}%`}
    />
  );
}

Range Slider

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function RangeSlider() {
  const [minPrice, setMinPrice] = React.useState(20);
  const [maxPrice, setMaxPrice] = React.useState(80);

  return (
    <Slider
      range
      minValue={minPrice}
      maxValue={maxPrice}
      onRangeChange={(min, max) => {
        setMinPrice(min);
        setMaxPrice(max);
      }}
      min={0}
      max={100}
      label="Price Range"
      minThumbAriaLabel="Minimum price"
      maxThumbAriaLabel="Maximum price"
    />
  );
}

Slider with Input Fields

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function SliderWithInputs() {
  const [value, setValue] = React.useState(50);

  return (
    <Slider
      value={value}
      onChange={setValue}
      min={0}
      max={100}
      inputPosition="right"
      label="Brightness"
    />
  );
}

Range Slider with Both Inputs

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function RangeSliderWithInputs() {
  const [min, setMin] = React.useState(1000);
  const [max, setMax] = React.useState(5000);

  return (
    <Slider
      range
      minValue={min}
      maxValue={max}
      onRangeChange={(minVal, maxVal) => {
        setMin(minVal);
        setMax(maxVal);
      }}
      min={0}
      max={10000}
      step={100}
      inputPosition="both"
      label="Budget Range"
      minThumbAriaLabel="Minimum budget"
      maxThumbAriaLabel="Maximum budget"
    />
  );
}

Anatomy

Import the component and use it directly:

import { Slider } from '@xsolla/xui-slider';

// Single value slider
<Slider
  value={value}                // Current value
  onChange={handleChange}      // Value change handler
  min={0}                      // Minimum bound
  max={100}                    // Maximum bound
  step={1}                     // Step increment
  label="Label"                // Label above slider
  inputPosition="none"         // Input field position
  showLabels={false}           // Show min/max labels
  disabled={false}             // Disabled state
  activeColor="brand"          // Color scheme
/>

// Range slider
<Slider
  range                        // Enable range mode
  minValue={minVal}            // Minimum selected value
  maxValue={maxVal}            // Maximum selected value
  onRangeChange={handleRange}  // Range change handler
  min={0}
  max={100}
/>

Examples

Slider Sizes

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function SliderSizes() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
      <Slider value={50} size="sm" label="Small" />
      <Slider value={50} size="md" label="Medium (default)" />
      <Slider value={50} size="lg" label="Large" />
      <Slider value={50} size="xl" label="Extra Large" />
    </div>
  );
}

Color Schemes

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function SliderColors() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
      <Slider value={60} activeColor="brand" label="Brand" />
      <Slider value={60} activeColor="brandExtra" label="Brand Extra" />
      <Slider value={60} activeColor="success" label="Success" />
      <Slider value={60} activeColor="warning" label="Warning" />
      <Slider value={60} activeColor="alert" label="Alert" />
      <Slider value={60} activeColor="neutral" label="Neutral" />
    </div>
  );
}

Slider with Icons

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";
import { Volume1, Volume2 } from "@xsolla/xui-icons-base";

export default function SliderWithIcons() {
  const [value, setValue] = React.useState(50);

  return (
    <Slider
      value={value}
      onChange={setValue}
      min={0}
      max={100}
      iconLeft={<Volume1 />}
      iconRight={<Volume2 />}
    />
  );
}

Step Slider

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function StepSlider() {
  const [value, setValue] = React.useState(50);

  return (
    <Slider
      value={value}
      onChange={setValue}
      min={0}
      max={100}
      step={10}
      showLabels
      label={`Value: ${value}`}
    />
  );
}

Disabled Slider

import * as React from "react";
import { Slider } from "@xsolla/xui-slider";

export default function DisabledSlider() {
  return (
    <Slider value={50} min={0} max={100} disabled label="Disabled slider" />
  );
}

API Reference

Slider

A slider component for value selection.

Slider Props:

Size Configuration:

| Size | Height | Track Height | Thumb Size | Input Width | | :--- | :----- | :----------- | :--------- | :---------- | | sm | 32px | 4px | 14px | 48px | | md | 40px | 6px | 16px | 56px | | lg | 48px | 6px | 18px | 64px | | xl | 56px | 8px | 20px | 72px |

Keyboard Navigation

Accessibility

Uses role="slider" semantic role
aria-valuenow, aria-valuemin, aria-valuemax for current state
Full keyboard navigation support
Focus indicator follows WCAG guidelines
Range mode has separate labels for min/max thumbs
Disabled state properly announced

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Slider

When to use

When not to use

Content guidelines

Behaviour guidelines

Accessibility

Installation

Demo

Basic Slider

Slider with Label

Range Slider

Slider with Input Fields

Range Slider with Both Inputs

Anatomy

Examples

Slider Sizes

Color Schemes

Slider with Icons

Step Slider

Disabled Slider

API Reference

Slider

Keyboard Navigation

Accessibility