An interactive spin wheel progressive web application with a user progression system. Perfect for making random selections, choosing winners, or making decisions in a fun and interactive way.
This app allows users to create customizable spinning wheels for random selection and decision making, while having fun doing so. Built as a single HTML page using pure HTML, Javascript, and CSS. It is a lightweight spin wheel application that runs entirely in the browser. With the assistance of Gemini 3 Pro, this app was built as to solve a real operational crisis of the technical team at Samuel Kripto.
Screenshot:
- ✨ Core Features
- Interactive Spin Wheel: Click to spin and randomly select an option.
- Customizable Options: Add, edit, or remove wheel segments.
- Easy to Use: Simple and intuitive interface.
- Single Page Application: No server required, runs entirely in your browser.
- Lightweight: Built with vanilla HTML, CSS, and JavaScript.
- Physics-Based Wheel: Realistic deceleration with a Damped Harmonic Oscillator physics.
- Weighted Probabilities: Support for weighted items using
Item:Weightsyntax (e.g.,Pizza:10) to increase winning chances. - Interactive Pins: 30 physical "pins" on the wheel edge that interact with the pointer (visual snapping and audio ticks).
- List Management: Create, rename, delete, and auto save multiple distinct lists (e.g., "Lunch Options", "Daily Standup", "Movie Night").
- Progress: Track your XP progress, levels, and achievements. Earn XP points and unlock various achievements on every spin!
- SpinCoin: Earn coins by spinning the wheel! Use them to buy items from the shop or unlock new customizations (eventually... shop features are not yet implemented).
- 🎨 Visuals & UI
- 3D Confetti: Physics-based confetti engine with wind resistance, tumbling, and semi-transparent paper effects.
- Theme System: Toggle between Auto (System), Light, and Dark modes.
- Responsive Design: Fully optimized for mobile and desktop, with a "Single Page App" feel (no scrolling on desktop).
- Mystery Mode: Toggle to hide item labels on the wheel ("?") for suspense.
- Interactive Power Meter:
- Tap-to-Spin: a quick click triggers an instant full-power spin.
- Hold-to-Charge: Holding the button charges a power meter. Release to spin with the selected strength.
- Visual Feedback: An animated ring fills up, changing color from blue to purple to red as power increases. The button shakes intensely at max power.
- Overheating FX: Continuing to hold the button after full charge triggers an "Overheating" sequence.
- Wheel Color Editor: Switch between default rainbow palette or define your own custom theme.
- 🤖 AI Integration (Gemini)
- AI List Generator: Generate creative lists (e.g., "Dinner ideas") using the Sparkle button.
- AI Voice Announcer: Optional Text-to-Speech announcement of the winner using Gemini's high-quality voices.
- Secure Settings: Dedicated UI for managing and persisting the Gemini API Key.
- 🛠️ Utilities
- Persistence: All settings (Inputs, History, Theme, API Key, Audio) are saved automatically to localStorage.
- History Tracking: Logs winners with relative timestamps (e.g., "2 minutes ago") and exact ISO tooltips.
- PWA Support: Installable as a standalone app on iOS and Android with custom icons and splash screen configuration.
- Share Functionality: Export current lists via a shareable URL (Base64 encoded).
- Open the app SpinWheel in your web browser.
- Add your custom options to the wheel.
- Click the spin button to make a random selection.
- The wheel will spin and land on one of your options.
You can customize the probability of each item winning by assigning a weight.
- Format:
Item Name:Weight - Higher number = Larger slice on the wheel.
- If no number is specified, it defaults to 1.
Example:
Pizza:5
Burger :1
Sushi: 1
Salad : 1
- Total Weight:
5 + 1 + 1 + 1 = 8 - Pizza: Has 5/8 of the total wheel (approx 62% chance).
- Others: Each have 1/8 of the total wheel (approx 12.5% chance).
- If the user doesn't type a number (e.g., just "Ramen"), the system defaults that item's weight to 1.
Get your Gemini API key from Google AI Studio.
The application supports a lightweight console mode for diagnostics and rapid testing.
- This mode is activated by creating a special list named
@console. - Commands are processed sequentially from top to bottom.
- Execution requires elevated permission, so this list must begin with the
#!sudodirective before any command entries are executed.
Within console mode, you can issue several debugging commands/instructions:
| Command | Description |
|---|---|
toast:achievement |
Toast animation for achievement unlocked. |
toast:quest |
Toast animation for quest completed. |
toast:levelup |
Toast animation for leveling up. |
toast:error |
Toast animation for errors (e.g., Invalid API key). |
toast:message |
message can be surfaced through the toast notification system by using the syntax. |
winner:name |
name can be surfaced through the winner modal by using the syntax. |
confetti |
Triggers the confetti animation at the current user's level. |
confetti:level |
Triggers the confetti animation at the specified level. |
snowfall |
Triggers the snowfall animation (for Christmas season). |
break |
Intentionally trigger a system failure (overheat). |
theme:mode |
Adjust the global theme. The enum value for mode is auto (or system), light, or dark. |
reset:achievements |
Reset all unlocked achievements. |
reset:quests |
Reset all completed daily quests. |
reset:level |
Reset the user level to 0. |
reset |
Restore the application to its default (factory) settings. |
Cheats (intended solely for testing, obviously) can be enabled by executing #!enable-cheats
command to elevate permissions, before inputting any of the cheat commands. Once activated, the
following commands allow you to manipulate progression state:
| Command | Description |
|---|---|
coins:amount |
Modify the 'SpinCoin' balance. The amount value may be positive or negative. |
xp:amount |
Modify experience points. The amount value may be positive or negative. |
levelup |
Jump directly to the next level threshold. |
The application includes a small set of special keywords that reveal additional contextual information when discovered through normal gameplay. When these keywords appear and you successfully spin to obtain them, they unlock brief informational panels.
@aboutreveals the app’s background and purpose.@authorprovides details about the creator behind the project.
The spin wheel uses HTML5 Canvas or CSS animations to create a smooth spinning effect. Each segment of the wheel represents a different option, and the selection is made using a randomization algorithm for fair results.
You can customize:
- Theme (auto, light-mode, or dark-mode)
- Sound effects (on or off, classic, wooden, metallic, crystal)
- Spin duration (quick 5s, normal 10s, or long 20s)
- Spin trail effects (on or off)
- Spin labels visibility (set it to hidden for a little bit of a "mystery" spin)
This project is inspired by popular picker wheel websites like PickerWheel.com, bringing the same functionality in a simple, self-contained format.
Simply clone this repository. No installation or build process required.
git clone https://github.com/samuelkripto/spinwheel.git
cd spinwheelServe locally using python3:
python3 -m http.serverNote
This app's original intention is to be a simple project that requires no build/compilation stage and ease of deployment. Generally not a recommended approach for larger apps/projects, because this has known limitations such as:
- using in-browser Babel compilation for JSX (less performant)
- no performance optimizations (e.g., React 19's memoization)
- partial TypeScript support
- no minification process for final delivery
This project is open source and available for personal, commercial, and educational use.
Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.