MultiSliderPro: Complete Documentation & Guide

v1.0.2 NPM React 16.8+ TypeScript Ready Accessible

A fully customizable, accessible React multi-range slider component with keyboard support, mobile compatibility, and Tailwind CSS styling. Perfect for price ranges, filtering, data visualization, and any application requiring multiple value selection.

Why Choose MultiSliderPro?
Built with accessibility in mind, featuring complete keyboard navigation, screen reader support, and mobile-first design. Highly customizable with Tailwind CSS classes and extensive prop options.

✨ Key Features

🎛️ Multiple Handles

Support for 2 or more handles with flexible value management and intuitive drag interactions.

⌨️ Keyboard Navigation

Complete keyboard support with arrow keys, home/end, page up/down, and shift modifiers for accessibility.

📱 Mobile Optimized

Touch events, responsive design, and mobile-friendly interactions for seamless mobile experiences.

♿ Accessibility First

ARIA labels, screen reader support, and WAI-ARIA guidelines compliance for inclusive design.

🎨 Fully Customizable

Colors, sizes, formatting, and behavior customization via props with Tailwind CSS integration.

🎯 Marks & Labels

Visual indicators with custom labels, value formatting, and flexible positioning options.

📦 Installation

# Using npm
npm install react-multi-slider-pro

# Using yarn
yarn add react-multi-slider-pro

Dependencies: Requires React 16.8+ (hooks support) and Tailwind CSS 2.0+ for styling.

🚀 Quick Start

Get started with MultiSliderPro in just a few lines of code:

import React, { useState } from ‘react’;
import { MultiSliderPro } from ‘react-multi-slider-pro’;

function App() {
  const [values, setValues] = useState([20, 80]);

  return (
    <div>
      <MultiSliderPro
        values={values}
        onChange={setValues}
        min={0}
        max={100}
        showLabels
        showValueLabels
      />
      <p>Selected range: {values[0]} – {values[1]}</p>
    </div>
  );
}
  

Demo:

📋 Complete Props Reference

Prop	Type	Default	Description
`values`	`number[]`	`[20, 80]`	Array of handle values
`min`	`number`	`0`	Minimum value
`max`	`number`	`100`	Maximum value
`step`	`number`	`1`	Step size for value changes
`disabled`	`boolean`	`false`	Disable the slider
`onChange`	`(values: number[]) => void`	`-`	Called when values change
`onChangeCommitted`	`(values: number[]) => void`	`-`	Called when user finishes changing
`showLabels`	`boolean`	`false`	Show min/max labels and value chips
`showValueLabels`	`boolean`	`false`	Show value labels above handles
`formatLabel`	`(value: number) => string`	`-`	Custom value formatting function
`trackColor`	`string`	`'bg-gray-300'`	Tailwind class for track color
`rangeColor`	`string`	`'bg-blue-500'`	Tailwind class for range color
`handleColor`	`string`	`'bg-blue-500'`	Tailwind class for handle color
`labelColor`	`string`	`'text-white'`	Tailwind class for label text color
`marks`	`Mark[]`	`[]`	Array of marks to display
`allowCross`	`boolean`	`false`	Allow handles to cross each other
`pushable`	`number`	`0`	Minimum distance between handles

💡 Practical Examples

Price Range Selector

Perfect for e-commerce filtering with formatted currency values:

const [priceRange, setPriceRange] = useState([25, 75]);

<MultiSliderPro
  values={priceRange}
  onChange={setPriceRange}
  min={0}
  max={500}
  step={5}
  showLabels
  showValueLabels
  formatLabel={(value) => `$${value}`}
  rangeColor=”bg-green-500″
  handleColor=”bg-green-600″
  aria-label=”Price range selector”
/>
  

Three-Handle Custom Styling

Multiple handles with custom colors and sizing:

const [values, setValues] = useState([20, 50, 80]);

<MultiSliderPro
  values={values}
  onChange={setValues}
  rangeColor=”bg-purple-500″
  handleColor=”bg-purple-600″
  trackHeight=”h-2″
  handleSize=”w-6 h-6″
  showValueLabels
  allowCross={false}
  pushable={10}
/>
  

Slider with Visual Marks

Add visual indicators with custom labels:

const marks = [
  { value: 0, label: ‘Min’ },
  { value: 25, label: ‘25%’ },
  { value: 50, label: ‘Mid’ },
  { value: 75, label: ‘75%’ },
  { value: 100, label: ‘Max’ }
];

<MultiSliderPro
  values={[30, 70]}
  marks={marks}
  showLabels
  step={5}
  formatLabel={(value) => `${value}%`}
/>
  

API Integration Pattern

Separate real-time updates from API calls:

const [filters, setFilters] = useState([20, 80]);

<MultiSliderPro
  values={filters}
  onChange={setFilters}           // Real-time UI updates
  onChangeCommitted={(finalValues) => {
    // Call API only when user finishes dragging
    fetchFilteredData(finalValues);
  }}
  showLabels
  showValueLabels
/>
  

⌨️ Keyboard Navigation

Key Combination	Action
`← ↓`	Move handle left/down by step
`→ ↑`	Move handle right/up by step
`Shift + ←↓→↑`	Move handle by large step (10% of range)
`Home`	Move handle to minimum value
`End`	Move handle to maximum value
`Page Down`	Move handle down by large step
`Page Up`	Move handle up by large step
`Tab`	Navigate between handles

♿ Accessibility Features

MultiSliderPro follows WAI-ARIA guidelines for maximum accessibility:

ARIA Support: Each handle has role="slider" with proper aria-valuemin, aria-valuemax, and aria-valuenow attributes
Screen Reader Friendly: Descriptive labels and value announcements
Keyboard Navigation: Complete keyboard support for handle manipulation
Focus Management: Proper focus indicators and tabbing behavior

<MultiSliderPro
  aria-label=”Temperature range selector”
  aria-labelledby=”temperature-label”
  values={[18, 24]}
  formatLabel={(temp) => `${temp}°C`}
/>
  

🎨 Styling Customization

Extensive customization options using Tailwind CSS classes:

Color Themes

// Blue theme (default)
<MultiSliderPro
  trackColor=”bg-gray-200″
  rangeColor=”bg-blue-500″
  handleColor=”bg-blue-600″
/>

// Green theme
<MultiSliderPro
  trackColor=”bg-gray-200″
  rangeColor=”bg-green-500″
  handleColor=”bg-green-600″
/>

// Custom gradient
<MultiSliderPro
  rangeColor=”bg-gradient-to-r from-purple-500 to-pink-500″
  handleColor=”bg-purple-600″
/>
  

Size Variations

// Compact size
<MultiSliderPro
  trackHeight=”h-0.5″
  handleSize=”w-4 h-4″
  containerHeight=”h-8″
/>

// Large size
<MultiSliderPro
  trackHeight=”h-3″
  handleSize=”w-8 h-8″
  containerHeight=”h-12″
/>
  

🔧 Handle Behavior Configuration

Prevent Handle Crossing

<MultiSliderPro
  allowCross={false}    // Handles cannot pass each other
  pushable={5}          // Minimum 5-unit gap between handles
  values={[20, 80]}
/>
  

Allow Handle Crossing

<MultiSliderPro
  allowCross={true}     // Handles can cross freely
  values={[20, 80]}
/>
  

🌐 Browser Support

✅ Chrome/Chromium 60+
✅ Firefox 55+
✅ Safari 12+
✅ Edge 79+
✅ Mobile browsers (iOS Safari, Chrome Mobile)

Note: Internet Explorer is not supported due to modern JavaScript features and CSS requirements.

🔍 Advanced Use Cases

Dynamic Value Formatting

const formatTimeRange = (minutes) => {
  const hours = Math.floor(minutes / 60);
  const mins = minutes % 60;
  return `${hours}:${mins.toString().padStart(2, ‘0’)}`;
};

<MultiSliderPro
  values={[480, 1020]} // 8:00 AM to 5:00 PM
  min={0}
  max={1440}           // 24 hours in minutes
  step={15}            // 15-minute intervals
  formatLabel={formatTimeRange}
  showValueLabels
/>
  

Data Visualization Integration

const [dataRange, setDataRange] = useState([2020, 2024]);

<MultiSliderPro
  values={dataRange}
  onChange={setDataRange}
  min={2000}
  max={2024}
  marks={yearMarks}
  showLabels
  onChangeCommitted={(years) => {
    updateChartData(years[0], years[1]);
  }}
/>
  

💖 Support This Project

If you find MultiSliderPro helpful, please consider supporting its development!

💝 Sponsor on GitHub ⭐ Star on GitHub

📝 TypeScript Support

While the component is written in JavaScript, TypeScript definitions can be easily added. The component exports clean interfaces for all props:

interface Mark {
  value: number;
  label?: string;
}

interface MultiSliderProProps {
  values?: number[];
  min?: number;
  max?: number;
  step?: number;
  disabled?: boolean;
  onChange?: (values: number[]) => void;
  onChangeCommitted?: (values: number[]) => void;
  // … other props
}
  

🎯 Best Practices

Performance: Use onChangeCommitted for API calls to avoid excessive requests
Accessibility: Always provide meaningful aria-label values
UX: Use appropriate step sizes for your use case (e.g., step={0.1} for decimals)
Mobile: Test touch interactions on various screen sizes
Styling: Ensure sufficient color contrast for accessibility compliance

🚨 Common Gotchas

State Management: Always use controlled components with the values prop and onChange handler.

Tailwind CSS: Ensure Tailwind CSS is properly configured in your project for styling to work correctly.

Handle Crossing: When allowCross={false}, handles will push each other. Use pushable to set minimum distance.

📚 Additional Resources

Questions or Need Help?
Feel free to open an issue on GitHub or reach out to the maintainer. Community contributions and feedback are always welcome!

MultiSliderPro v1.0.2 – Built with ❤️ for the React community
MIT License | Created by Andrei-Constantin Alexandru

MultiSliderPro: Complete Documentation & Guide