React Ranger 🎛

A headless render-prop component for building range and multi-range sliders in React

• 2kb gzipped. Wow!
• Render-Prop pattern allows you to render and style the slider however you want.

Examples

• Codesandbox.io (contains all examples below)
  • Simple
  • Custom Components
  • Multi-Range
  • Custom Steps

Chat with us on Spectrum!

Need Help? Click here to sign up for the React-Tools Spectrum community. We are constantly discussing implementation details and answering questions. :)

Installation

$ yarn add react-ranger
# or
$ npm install --save react-ranger

Sample Usage

The following is a very basic example of a single range input that looks similar to Chrome's default appearance.

import ReactRanger from "react-ranger";

class SimpleExample extends React.Component {
  state = {
    value: 5
  };
  render() {
    const { value } = this.state;
    return (
      <ReactRanger
        min={0}
        max={100}
        stepSize={5}
        value={value}
        onChange={value =>
          this.setState({
            value
          })
        }
      >
        {({ getTrackProps, handles }) => (
          <div
            {...getTrackProps({
              style: {
                height: "4px",
                background: "#ddd",
                boxShadow: "inset 0 1px 2px rgba(0,0,0,.6)",
                borderRadius: "2px"
              }
            })}
          >
            {handles.map(({ value, active, getHandleProps }) => (
              <div
                {...getHandleProps({
                  style: {
                    width: "12px",
                    height: "12px",
                    borderRadius: "100%",
                    background:
                      "linear-gradient(to bottom, #eee 45%, #ddd 55%)",
                    border: "solid 1px #888"
                  }
                })}
              />
            ))}
          </div>
        )}
      </ReactRanger>
    );
  }
}

Props

• children: func.isRequired A Function as a child that receives the following props:
  • getTrackProps(userProps): func - A function that takes optional props and returns the combined necessary props for the track component.
  • ticks: array - Ticks to be rendered. Each tick has the following props:
    • value: number - The tick number to be displayed
    • getTickProps(userProps): func - A function that take optional props and returns the combined necessary props for the tick component.
  • segments: array - Segments to be rendered. Each segment has the following props:
    • value: number - The segments ending value
    • getSegmentProps(userProps): func - A function that take optional props and returns the combined necessary props for the segment component.
  • handles: array - Handles to be rendered. Each handle has the following props:
    • value: number - The current value for the handle
    • active: boolean - Denotes if the handle is currently being dragged.
    • getHandleProps(userProps): func - A function that take optional props and returns the combined necessary props for the handle component.
  • activeHandleIndex: oneOfType([null, number]) - The zero-based index of the handle that is currently being dragged, or null if no handle is being dragged.
• min: number.isRequired - The minimum limit for the range
• max: number.isRequired - The maximum limit for the range
• value: oneOfType([number, arrayOf(number)]).isRequired - The current value (or values) for the range
• interpolator: shape({ getPercentageForValue: PropType.func, getValueForClientX: PropTypes.func}) - Interpolator to use. See Interpolation
• stepSize: number.isRequired - The distance between selectable steps
• steps: arrayOf(number) - An array of custom steps to use. This will override stepSize,
• tickSize: number
• ticks: arrayOf(number): Default: 10 - An array of custom ticks to use. This will override tickSize,
• onChange: func - A function that is called with the following parameters:
  • newValue - The new value or values for the range
• onTrackClick: func - A function that is called when the tracked is clicked with the following parameters:
  • stepValue - The value that was clicked, but rounded to the nearest step.
  • preciseValue - The value that was clicked, with decimal precision.
• onPress: func - A function that is called when a handle is pressed.
• onDrag: func - A function that is called when a handled is dragged.
• onRelease: func - A function that is called when a handle is released.

Interpolation

By default, react-ranger uses linear interpolation between data points. We also provide a logarithmic interpolator and an easy way to create your own.

import ReactRanger, { logInterpolator } from "react-ranger";
...
<ReactRanger
  min={0}
  max={100}
  stepSize={5}
  value={value}
  interpolator={logInterpolator}
>

One can create their own interpolator by passing an object that implements the interface described below

{
  // Takes the value & range and returns a percentage [0, 100] where the value sits from left to right
  getPercentageForValue: (val: number, min: number, max: number): number

  // Takes the clientX (offset from the left edge of the ranger) along with the dimensions
  // and range settings and transforms a pixel coordinate back into a value
  getValueForClientX: (clientX: number, trackDims: object, min: number, max: number): number
}

Contributing

We are always looking for people to help us grow react-ranger's capabilities and examples. If you have an issue, feature request, or pull request, let us know!

License

React Ranger uses the MIT license. For more information on this license, click here.