willwull / circle-slider

A slider, except it's round

circle-slider

A slider, except it's round. Pretty good for selecting angles and stuff.

Demo here.

Install

$ npm i circle-slider

Usage

Basic usage:

HTML:

<div id="whatever"></div>

JS:

// Import the module at the top of your file
const CircleSlider = require("circle-slider");

// or ES6 style
import CircleSlider from "circle-slider";

// The id of your target element as the first arg
const cs = new CircleSlider("whatever");

All you have to do on the HTML side is to create a div with some id, which is the first parameter in the constructor of CircleSlider.

All you need is to create a div, the elements for the handle (and its container) will be created for you.

You can put anything you want inside the div, e.g. a div which displays the current angle (see the demo).

Options

The constructor takes an optional second parameter which looks like this:

{
  // e.g. snap to every 45 degrees
  snap: Number,

  // positive direction
  clockwise: Boolean,

  // which position 0 degrees is
  startPos: "top"|"bottom"|"left"|"right",
}

I'll emphasize that startPos changes where 0 degrees is, so if you instead want, for example, 0 to be at the top, but want the slider to start at 90 degrees, you should call setAngle(90) (see below) after creating the slider.

Example usage:

const options = {
  snap: 45,
  clockwise: false,
  startPos: "top",
};
const cs = new CircleSlider("id", options);

You can also write the first parameter with a #:

new CircleSlider("#id");

With or without #, there is no difference in functionality, so choose which one you prefer.

Methods

Here is the stuff you can do with CircleSlider:

// get the current angle value
cs.getAngle();

// set the angle manually
cs.setAngle(45);

// fires every time the slider is moved
// the emitted event will give you the angle
cs.on("sliderMove", (angle) => {
    someDiv.textContent = angle;
})

// fires every time the handle stops moving
// can be useful to avoid heavy operations every time the
// handle moves
cs.on("sliderUp", (angle) => {
    someDiv.textContent = angle;
})

Note that the sliderMove event gets triggered when using setAngle.

Since CircleSlider extends eventemitter3, you can also use functions like once instead of on.

Further reading here (eventemitter3 uses the same API as node events).

Styling

I leave most styling up to you! However, there are some CSS rules that you must use in order for the handle two rotate properly and stuff. Here are some good defaults to get started with:

#slider {
  /*
    position: relative is needed for the handle to be
    positioned correctly, and border-radius: 100% just
    makes the div round.
  */
  position: relative;
  border-radius: 100%;

  /* Other than the above two, go wild! */
  height: 300px;
  width: 300px;
  background: linear-gradient(90deg, #FF9A9E, #FAD0C4);
}

/*
  Probably best to paste this exactly as is.
  These CSS rules make sure that the handle rotates
  properly, so don't change anything here.
*/
.cs-handle-container {
  position: absolute;
  left: 0;
  right: 0;
  top: 50%;
  height: 2px;
  margin-top: -1px;
}

/* Also paste as is */
.cs-handle {
  position: absolute;
  transform: translateY(-50%);
}

/* the appearance of the handle, feel free to change! */
#slider .cs-handle {
  height: 30px;
  width: 30px;
  /*
    Change 'right' to change the offset from the edge.
    E.g right: 0 puts the handle just next to the edge
    of #slider, on the inside
  */
  right: -15px;
  cursor: default;
  border-radius: 100%;
  background: linear-gradient(180deg, #FFFFFF, #efefef);
  box-shadow: rgba(0, 0, 0, 0.3) 0 1px 10px 0;
}

#slider .cs-handle:active {
  background: linear-gradient(180deg, #EBEBEB, #DFDFDF)
}

circle-slider's Issues

setAngle sets wrong angle

Top, clockwise and bottom, counter clockwise sets (360-x) instead of x.

Add more options

More options can include:

• Choosing where 0 deg is (top, left, right, bottom)
• Choosing angle direction (clockwise, counterclockwise)

Angle returns as NaN on Android

I tried this on some Android phones, namely Galaxy S8 and S7, and none of them work properly.
When trying to move the handle in the demo page, the number changes to NaN, and the handle doesn't move either.

This could be caused by a number of methods, like _moveHandle, _getRawAngle, _getCenter, or _radToDeg, but I don't own any Android devices to test with.

Fails to build in a React project

Tried to import this into a React project (created with create-react-app), and when building, it outputs this error message:

Failed to minify the code from this file:

./node_modules/circle-slider/src/index.js line 3:0

Read more here: http://bit.ly/2tRViJ9

SliderUp fires multiple times

As the title states, the sliderUp event gets fired multiple times, caused by the fact that mouseUp gets fired multiple times. I'd assume that touchend also has this problem, although I haven't tested that.