SpinWheel SDK

A lightweight, customizable JavaScript library for creating interactive spin-the-wheel components.

Installation

Direct Include

<script src="spinwheel.js"></script>

NPM (if published)

npm install spinwheel-sdk

Quick Start

<div id="wheel"></div>
<script src="spinwheel.js"></script>
<script>
  const wheel = new SpinWheel('wheel', {
    slots: ['Prize 1', 'Prize 2', 'Prize 3', 'Prize 4'],
    onWinner: (winner, index) => {
      alert(`You won: ${winner}`);
    }
  });
</script>

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | slots | Array | ['Prize 1', ...] | Array of slot names/labels or objects with {name, index} | | width | Number | 400 | Wheel width in pixels | | height | Number | 400 | Wheel height in pixels | | duration | Number | 4 | Spin duration in seconds | | spins | Number | 5 | Number of full rotations | | easing | String | 'cubic-bezier(0.17, 0.67, 0.12, 0.99)' | Animation easing (ease-out, bounce, linear, ease-in-out) | | pointerColor | String | '#ff4757' | Pointer color | | pointerSize | Number | 40 | Pointer size in pixels | | borderWidth | Number | 2 | Slot border width | | borderColor | String | '#ffffff' | Slot border color | | shadowColor | String | '#000000' | Wheel shadow color | | wheelBackgroundColor | String | '#ffffff' | Wheel background | | wheelContainerColor | String | '#ffffff' | Wheel container background | | themeColors | Array | ['#FF6B6B', '#4ECDC4'] | Two colors for alternating slots | | headerText | String | '🎡 Spin the Wheel' | Header text | | headerDescription | String | '' | Description text below header | | headerBorderWidth | Number | 3 | Header border width | | headerBorderColor | String | '#667eea' | Header border color | | centerText | String | 'SPIN' | Center circle main text | | centerSubText | String | '' | Center circle sub text (smaller, wraps at 8 chars) | | showDropdown | Boolean | true | Show winner selection dropdown | | winnerApi | String | null | API endpoint to fetch winner index | | apiHeaders | Object | {} | API request headers (JSON object) | | apiParams | Object | {} | API request URL parameters (JSON object) | | showConfetti | Boolean | true | Show confetti animation on win | | confettiCount | Number | 100 | Number of confetti pieces | | confettiDuration | Number | 3 | Confetti animation duration (seconds) | | showSettings | Boolean | true | Show settings panel (for demo page) | | onWinner | Function | null | Callback when spin completes |

API Methods

spin(winnerIndex)

Spin the wheel. Optionally specify winner index.

wheel.spin(); // Random winner
wheel.spin(2); // Force winner at index 2

setSlots(slots)

Update slot names dynamically. Accepts array of strings or objects with name and index.

wheel.setSlots(['New Prize 1', 'New Prize 2', 'New Prize 3']);
// Or with custom indices:
wheel.setSlots([
  { name: 'Prize A', index: '1' },
  { name: 'Prize B', index: '2' },
  { name: 'Prize C', index: '3' }
]);

setWinner(index)

Set the next winner (use before calling spin).

wheel.setWinner(1);
wheel.spin();

Examples

Basic Example

const wheel = new SpinWheel('wheel', {
  slots: ['🎁 Gift', '🏆 Trophy', '⭐ Star']
});

With Callback

const wheel = new SpinWheel('wheel', {
  slots: ['Prize A', 'Prize B', 'Prize C'],
  onWinner: (winner, index) => {
    console.log(`Winner: ${winner} at position ${index}`);
    // Send to backend, show modal, etc.
  }
});

Custom Styling

const wheel = new SpinWheel('wheel', {
  slots: ['Red', 'Blue', 'Green'],
  themeColors: ['#e74c3c', '#ffffff'],
  pointerColor: '#e74c3c',
  headerText: '🎯 Spin to Win!',
  headerBorderColor: '#e74c3c',
  centerText: 'SPIN',
  centerSubText: 'TO WIN',
  duration: 5,
  spins: 8
});

With API Call for Winner Selection

const wheel = new SpinWheel('wheel', {
  slots: ['Prize 1', 'Prize 2', 'Prize 3'],
  winnerApi: 'https://api.example.com/get-winner',
  apiHeaders: { 'Authorization': 'Bearer token123' },
  apiParams: { 'userId': '12345' },
  showDropdown: false
});
// API should return: { "winnerIndex": 0 } or { "index": 0 }

With Dropdown Selection

const wheel = new SpinWheel('wheel', {
  slots: ['Prize 1', 'Prize 2', 'Prize 3'],
  showDropdown: true // default, displays slot index values (1, 2, 3...)
});

With Confetti Settings

const wheel = new SpinWheel('wheel', {
  slots: ['Prize 1', 'Prize 2', 'Prize 3'],
  showConfetti: true,
  confettiCount: 150,
  confettiDuration: 4
});

Controlled Winner

const wheel = new SpinWheel('wheel', {
  slots: ['Prize 1', 'Prize 2', 'Prize 3']
});

// Force specific winner
document.getElementById('btn').addEventListener('click', () => {
  wheel.spin(1); // Always win Prize 2
});

Browser Support

Works in all modern browsers that support ES6.

License

MIT