Slider

v0.4.2

Documentation Under Review

Overview

The Slider component provides an intuitive way for users to select numeric values within a defined range. Built on Radix UI primitives, it supports single value selection, range selection with dual thumbs, and visual segment markers for precise value indication.

Installation

npm install @pmi/catalyst-slider

Usage

Basic Single Value Slider

Range Slider

Select a range of values using two thumbs.

Slider with Segments

Display visual markers at each step position.

Range Slider with Segments

Combine range selection with segment markers.

Disabled State

Custom Styling

Customize the slider appearance with Tailwind CSS classes.

Real-World Product Examples

API Reference

SliderRoot

The root container that manages slider state and behavior.

SliderTrack

The track element that contains the slider range.

SliderRange

The filled portion of the track representing the selected range.

SliderThumb

The draggable handle for selecting values. Use multiple thumbs for range selection.

SliderSegment

Visual markers displayed at step positions along the track.

Accessibility

Keyboard Navigation

• Arrow Left/Down: Decrease value by one step
• Arrow Right/Up: Increase value by one step
• Home: Jump to minimum value
• End: Jump to maximum value
• Page Down: Decrease value by larger increment
• Page Up: Increase value by larger increment

ARIA Attributes

• role="slider": Applied to thumb elements
• aria-label: Required for each thumb to identify purpose
• aria-valuemin: Minimum value
• aria-valuemax: Maximum value
• aria-valuenow: Current value
• aria-disabled: Indicates disabled state

Best Practices

1. Always provide aria-label: Each thumb needs a descriptive label
2. Use appropriate step sizes: Ensure values are meaningful for your use case
3. Consider range constraints: Use minStepsBetweenThumbs for range sliders
4. Provide visual feedback: Show current value(s) near the slider
5. Test keyboard navigation: Verify all keyboard interactions work correctly

Design Guidelines

When to Use

• Adjusting numeric values within a defined range
• Volume, brightness, or other continuous controls
• Filtering data by numeric ranges
• Setting price ranges or time periods
• Configuring threshold values

When Not to Use

• Selecting from discrete options (use RadioGroup or Select)
• Binary choices (use Switch or Checkbox)
• Precise numeric input required (use TextField)
• Many small increments (consider TextField with validation)

Understanding Segment Positioning

When using segments with sliders, a MutationObserver is employed to fix positioning issues caused by Radix UI's internal calculations. The observer removes calc() offsets that can misalign segments with their intended step positions.

How it works:

1. Segments are positioned at calculated percentages along the track
2. The observer watches for style changes on thumb parent elements
3. When a calc() expression is detected, it's simplified to the base percentage
4. This ensures segments align perfectly with step positions

This is necessary because Radix UI applies transforms to center thumbs at their values, which can conflict with segment positioning.

Custom Styling Patterns

The custom styling example demonstrates using nested selectors to style Radix UI primitives that don't expose direct class props:

// Target slider thumbs through role selector
'[&_[role=slider]]:bg-pmi-aqua-500';

// Style on hover
'[&_[role=slider]:hover]:bg-pmi-aqua-700';

// Focus-visible state
'[&_[role=slider]:focus-visible]:bg-pmi-aqua-500';

This pattern allows consistent theming across all slider components while maintaining the primitive structure.