TanStack Ranger

TanStack Ranger is a feature-rich and lightweight headless utility for building range sliders. Because it is 'headless', it does not provide or render any UI elements out of the box, allowing you to dictate your own UI and styling.

Key characteristics include:

• 100% Typesafe: Full TypeScript support for reliable development.
• Lightweight: Small footprint (~10kb).
• Extensible: Designed to be easily customized and extended.
• UI Agnostic: Does not dictate how your components should look or be structured.

TanStack Ranger provides several core capabilities for building range inputs:

• Headless UI: Complete control over your component's styling and structure.
• Single or Multiple Handles: Support for both single-value sliders and multi-handle range pickers.
• Handle Divider Items: Ability to include items between handles.
• Custom Steps or Step-Size: Control over the increments or granularity of the range selection.
• Custom Ticks: Support for custom tick marks and labels along the range.

The Ranger class is the core engine of the library. It centralizes all the logic required to build a range component and interact with its state. The instance is responsible for managing:

• Value Range: The current selection or bounds of the range.
• Snap Interpolation: The logic for snapping values to specific points.
• Ticks (labels) generation: The calculation and generation of tick marks and labels.

Ranger is a headless utility library, meaning it does not provide pre-built UI components or markup. Instead, it manages the underlying logic and state. To build a user interface, you must use the state and callbacks provided by Ranger's hooks to render your own custom markup (e.g., sliders, inputs, or tables).

This approach provides:

• Separation of Concerns: Ranger handles logic while you handle the look and feel.
• Maintenance: A smaller API surface area makes the library easier to maintain.
• Extensibility: You are not restricted by pre-defined UI patterns and can handle unique edge cases.

By default, @tanstack/react-ranger uses linear interpolation to map values to the slider track. If you need a non-linear scale (such as logarithmic), you can provide a custom interpolator object in your component options. This allows the slider to represent values where the visual distance between points is not constant, which is useful for scales like decibels or frequency.

// Example of providing a custom interpolator
<Ranger
  // ... other props
  interpolator={{
    getPercentageForValue: (val, min, max) => {
      // Custom logic to return percentage [0, 100]
    },
    getValueForClientX: (clientX, trackDims, min, max) => {
      // Custom logic to return value from pixel coordinate
    }
  }}
/>

To run the React example demonstrating custom styles, use a package manager to install dependencies and start the development server.

npm install
# or
yarn

npm run start
# or
yarn start

To run the basic React example provided in the repository, install the dependencies and start the development server using your preferred package manager.

npm install
npm run start

# or using yarn
yarn
yarn start

To use TanStack Ranger with React, install the @tanstack/react-ranger package using your preferred NPM package manager.

npm install @tanstack/react-ranger

You can install TanStack Ranger using any NPM package manager. The package you install depends on your framework of choice.

Currently, the primary supported package is for React. Other framework integrations (Solid, Vue, Svelte, and Angular) are planned for future release.

To run the custom-steps React example locally, install the dependencies and start the development server using your preferred package manager.

npm install
# or
yarn

npm run start
# or
yarn start

To run the React example demonstrating the logarithmic interpolator, navigate to the example directory and use your preferred package manager to install dependencies and start the development server.

npm install
# or
yarn

npm run start
# or
yarn start