🎡 mystery-game-modal

Mystery Game Modal is a dynamic, rotating picker component that selects a random item from a list — perfect for games, movie posters, music albums, or any creative use case where randomness adds excitement!

✨ Features

• 🔄 Random Picker with Spin Animation – simulates a spinning wheel to randomly choose an item.
• 🌀 Mystery Mode – continuous, suspenseful rotation until stopped.
• 🖼️ Image-Based Items – each item can include an image, title, alt text, and optional metadata like RTP.
• 🧭 Directional Spin – supports left or right rotation.
• 💡 Lightweight and Pluggable – easy to integrate with minimal setup.

📦 Installation

npm install mystery-game-modal

or

yarn add mystery-game-modal

🚀 Usage Example

import React, { useState } from "react";
import Spin, { SpinItem } from "mystery-game-modal";

const App = () => {
  const [triggerSpin, setTriggerSpin] = useState(false);
  const [resetSignal, setResetSignal] = useState(0);

  const items: SpinItem[] = [
    {
      imageUrl: "https://example.com/images/movie1.jpg",
      alt: "Inception",
      index: 0,
      title: "Inception",
      point: 95,
      path: "/movies/inception"
    },
    {
      imageUrl: "https://example.com/images/movie2.jpg",
      alt: "Interstellar",
      index: 1,
      title: "Interstellar",
      point: 90,
      path: "/movies/interstellar"
    },
    // ...more items
  ];

  const handleSpinEnd = () => {
    console.log("Spin finished!");
  };

  const handleSelect = (item: SpinItem) => {
    console.log("Selected:", item);
  };

  return (
    <div>
      <Spin
        items={items}
        isMysteryMode={false}
        triggerSpin={triggerSpin}
        resetSignal={resetSignal}
        direction="right"
        onSpinEnd={handleSpinEnd}
        onSelect={handleSelect}
      />
      <button onClick={() => setTriggerSpin(true)}>Spin Now</button>
      <button onClick={() => setResetSignal(prev => prev + 1)}>Reset</button>
    </div>
  );
};

export default App;

🔧 Props

| Prop | Type | Description | |----------------|----------------------------|-----------------------------------------------------------------------------| | items | SpinItem[] | Array of items to choose from (must include imageUrl, alt, title, etc). | | isMysteryMode| boolean | If true, the wheel rotates continuously until stopped manually. | | triggerSpin | boolean | When set to true, starts the spin animation. | | resetSignal | number | A changing number to trigger reset of internal state. | | onSpinEnd | () => void | Callback when the spin animation ends. | | direction | "left" | "right" | (Optional) Direction of spin. Defaults to "right". | | onSelect | (item: SpinItem) => void | (Optional) Called with the selected item once spin completes. |

🧩 SpinItem Interface

interface SpinItem {
  imageUrl: string; // Required image source
  alt: string;      // Alt text for accessibility
  index: number;    // Unique index
  title: string;    // Display title
  point?: number;   // Optional rating or metadata
  path: string;     // A related route or identifier
}

🧙‍♂️ Use Cases

• 🎮 Random game selector (e.g. slot games, arcade titles)
• 🎬 Movie roulette (e.g. spin to watch a random film)
• 🎵 Shuffle music albums visually
• 🧸 Mystery box unboxing UI
• 💼 Team picker or giveaway tool

📎 License

MIT — feel free to use and modify!