Spin Wheel

An easy to use, themeable component for randomising choices and prizes.

Features

• Vanilla JavaScript (ES6).
• No dependencies.
• Simple, easy to use API.
• Spin by applying momentum and drag, or animate to a specific angle with easing.
• Interactable with click-drag or touch-flick.
• Responsive layout (resizes automatically to fit it's container).
• Easily themeable:
  • Give items their own color and weight.
  • Rotate labels and change alignment.
  • Draw images on items, the wheel, and the foreground.
  • Apply repeating colour sets.
• Callbacks for events like onSpin and onCurrentIndexChange.
• Clockwise and anti-clockwise spinning.

Examples

• Basic ESM
• Basic IIFE
• Basic Vue
• Spin to a specific item
• Multiple Wheels
• Themes
• Playground (for testing and troubleshooting)

Installation

ESM

import {Wheel} from 'https://cdn.jsdelivr.net/npm/spin-wheel@5.0.2/dist/spin-wheel-esm.js';

IIFE

<script src="https://cdn.jsdelivr.net/npm/spin-wheel@5.0.2/dist/spin-wheel-iife.js"></script>

Local

npm install spin-wheel

How to make your own wheel

// 1. Configure the wheel's properties:
const props = {
  items: [
    {
      label: 'one',
    },
    {
      label: 'two',
    },
    {
      label: 'three',
    },
  ]
}

// 2. Decide where you want it to go:
const container = document.querySelector('.wheel-container');

// 3. Create the wheel in the container and initialise it with the props:
const wheel = new Wheel(container, props);

How to spin the wheel

For multiplayer games or awarding prizes with actual value, the best way is to call Wheel.spinToItem(). The wheel will spin for a certain duration, and once finished the pointer will be pointing at the specified item. You should always calculate the winning item on the back-end, for example:

const winningItemIndex = await fetchWinningItemIndex();
const duration = 4000;
const easing = easing.cubicOut;
wheel.spinToItem(winningItemIndex, duration, true, 2, 1, easing)

If precision is not important, you can use Wheel.spin() to immediately start spinning the wheel at a certain speed, which will be reduced over time according to Wheel.rotationResistance. You can also set Wheel.isInteractive = true to allow the user to spin the wheel themselves by dragging or flicking.

How to draw the pointer

The wheel doesn't have a built-in pointer, instead you set Wheel.pointerAngle and draw the pointer yourself. This is because there are many ways you might want the pointer to appear and behave, for example you might want to animate it.

Your options for drawing the pointer are:

• Overlay an image using Wheel.overlayImage
• Overlay something using the DOM

Images and fonts

Images are passed as instances of HTMLImageElement and should be pre-loaded, otherwise there will be an initial delay (or flicker) while the browser downloads them. Fonts should also be pre-loaded for the same reason. See the code behind the themes example for an example of how to pre-load images and fonts.

Configuration

Everything is easy to configure. The wheel is responsive and resizes automatically to fit it's container, so when the size of the container changes you don't have to worry about updating fiddly things like widths and font sizes. For that reason, some numeric properties are expressed as percentages, while others are expressed as pixels.

• Percentage properties are a percent of the container size. For example, a Wheel.radius of 0.9 means the wheel will fill 90% of the container.

• Pixel properties are relative to a container size of 500px. For example, a Wheel.LineWidth of 1 will be exactly 1px when the container size is 500px.

Labels are also simple to configure because the font size is calculated automatically. You can optionally set Wheel.itemLabelFontSizeMax (in pixels), but otherwise the largest item label will be sized to fit between Wheel.itemLabelRadius (percent) and Wheel.itemLabelRadiusMax (percent).

Here's a handy diagram:

Methods for Wheel

Properties for Wheel

Note: setting a property to undefined will reset it to the default value.

Events for Wheel

onCurrentIndexChange(event = {})

Raised when a new item is pointed at. This can be used to change the color of the current item, or play a 'ticking' sound.

onRest(event = {})

Raised when the wheel comes to a rest after spinning.

onSpin(event = {})

Raised when the wheel has been spun.

Methods for Item

Properties for Item

Note: setting a property to undefined will reset it to the default value.

Acknowledgements

Inspired by random-wheel.