Socket
Socket
Sign inDemoInstall

react-ranger

Package Overview
Dependencies
6
Maintainers
1
Versions
25
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

react-ranger

Hooks for building range and multi-range sliders in React


Version published
Maintainers
1
Weekly downloads
10,034
decreased by-4.66%

Weekly downloads

Readme

Source

React Ranger Header

Hooks for building range and multi-range sliders in React

#TanStack semantic-release Join the discussion on Github

Enjoy this library? Try them all! React Table, React Query, React Form, React Charts

Quick Features

  • Headless!
  • Single or Multiple Handles
  • Handle Devider Items
  • Custom Steps or Step-Size
  • Custom Ticks

Examples

Sponsors

This library is being built and maintained by me, @tannerlinsley and I am always in need of more support to keep projects like this afloat. If you would like to get premium support, add your logo or name on this README, or simply just contribute to my open source Sponsorship goal, visit my Github Sponsors page!

Diamond Sponsors

Get Your Logo Here!

Gold Sponsors

Get Your Logo Here!

Silver Sponsors

Get Your Logo Here!

Bronze Sponsors

Supporters

Fans

  • Get your name here!

Become a Sponsor

Documentation

Installation

$ npm i --save react-ranger
# or
$ yarn add 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'

function App() {
  const [values, setValues] = React.useState([10])

  const { getTrackProps, handles } = useRanger({
    values,
    onChange: setValues,
    min: 0,
    max: 100,
    stepSize: 5,
  })

  return (
    <>
      <div
        {...getTrackProps({
          style: {
            height: '4px',
            background: '#ddd',
            boxShadow: 'inset 0 1px 2px rgba(0,0,0,.6)',
            borderRadius: '2px',
          },
        })}
      >
        {handles.map(({ getHandleProps }) => (
          <div
            {...getHandleProps({
              style: {
                width: '12px',
                height: '12px',
                borderRadius: '100%',
                background: 'linear-gradient(to bottom, #eee 45%, #ddd 55%)',
                border: 'solid 1px #888',
              },
            })}
          />
        ))}
      </div>
    </>
  )
}

Options

  • value: Array<number> - The current value (or values) for the range
    • Required
  • min: number - The minimum limit for the range
    • Required
  • max: number - The maximum limit for the range
    • Required
  • stepSize: number - The distance between selectable steps
    • Required
  • 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: Function(newValue) - A function that is called when the handle is released
  • onDrag: Function(newValue) - A function that is called when a handled is dragged
  • interpolator: { getPercentageForValue: Function(value) => decimal, getValueForClientX: Function(x) => value}
    • The Interpolator to use
    • Defualts to the bundled linear-scale interpolator See the Interpolation section for more info

Returns

useRanger returns an object with the following properties:

  • 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.

Interpolation

By default, react-ranger uses linear interpolation between data points, but allows you to easily customize it to use your own interpolation functions by passing an object that implements the following interface:

const interpolator = {
  // 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
}

Here is an exmaple of building and using a logarithmic interpolator!

import { useRanger } from 'react-ranger'

const logInterpolator = {
  getPercentageForValue: (val, min, max) => {
    const minSign = Math.sign(min)
    const maxSign = Math.sign(max)

    if (minSign !== maxSign) {
      throw new Error(
        'Error: logarithmic interpolation does not support ranges that cross 0.'
      )
    }

    let percent =
      (100 / (Math.log10(Math.abs(max)) - Math.log10(Math.abs(min)))) *
      (Math.log10(Math.abs(val)) - Math.log10(Math.abs(min)))

    if (minSign < 0) {
      // negative range, means we need to invert our percent because of the Math.abs above
      return 100 - percent
    }

    return percent
  },
  getValueForClientX: (clientX, trackDims, min, max) => {
    const { left, width } = trackDims
    let value = clientX - left
    value *= Math.log10(max) - Math.log10(min)
    value /= width
    value = Math.pow(10, Math.log10(min) + value)
    return value
  },
}

useRanger({
  interpolator: logInterpolator,
})

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Tanner Linsley

💻 🤔 💡 🚧 👀

Evert Timberg

💻 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

FAQs

Last updated on 11 Sep 2020

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc