slot-machine

A responsive, configurable React slot machine / reel component. Use one component per reel; combine multiple reels for a full slot grid. No external UI or state library required—bring your own items and styling.

Framework-agnostic: All layout uses inline styles (no Tailwind or CSS required). Works in Vite, Next.js, CRA, or any React app. Give the wrapper a defined size (e.g. height: 400px or width: 100%; height: 100% inside a sized parent) so the reel centers and displays correctly.

Install

npm install slot-machine
# or
yarn add slot-machine
pnpm add slot-machine

Peer dependencies

• react >= 18
• react-dom >= 18

Basic usage

import { SlotMachine, type SlotItem, type SlotMachineHandle } from "slot-machine";
import { useRef } from "react";

const items: SlotItem[] = [
  { id: "1", image: "/cherry.png", name: "Cherry" },
  { id: "2", image: "/lemon.png", name: "Lemon" },
  { id: "3", image: "/seven.png", name: "Seven" },
];

function App() {
  const ref = useRef<SlotMachineHandle>(null);

  return (
    <div style={{ width: "100%", height: "400px" }}>
      <SlotMachine
        ref={ref}
        items={items}
        onSpinEnd={(result) => console.log("Landed on", result)}
      />
      <button onClick={() => ref.current?.spin()}>Spin</button>
    </div>
  );
}

Multiple reels (slot count)

Render one SlotMachine per reel and control spin via refs:

const SLOT_COUNT = 6;
const refs = useRef<(SlotMachineHandle | null)[]>([]);

<div style={{ display: "flex", gap: 8, width: "100%", height: 450 }}>
  {Array.from({ length: SLOT_COUNT }).map((_, i) => (
    <div key={i} style={{ flex: 1, minWidth: 0 }}>
      <SlotMachine
        ref={(r) => { refs.current[i] = r; }}
        items={items}
        slotIndex={i}
        forcedResult={serverResults[i]} // optional: fix outcome per reel
        onSpinEnd={(result) => handleReelEnd(i, result)}
      />
    </div>
  ))}
</div>
<button onClick={() => refs.current.forEach((r) => r?.spin())}>
  Spin all
</button>

Props (input data & settings)

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | T[] | required | Pool of items for the reel (and optional forced result). | | slotIndex | number | 0 | Index of this reel (e.g. 0..5 for 6 reels). | | forcedResult | T \| null | null | If set, this reel stops on this item (e.g. from server). | | duration | number | 2500 | Spin duration in ms. | | twistDuration | number | 400 | Twist-back (snap to center) duration in ms. | | orientation | "vertical" \| "horizontal" | "vertical" | Reel direction. | | itemSize | number | derived | Item size in px. Omit for responsive (size from container). | | itemGap | number | 20 | Gap around each item in px. | | reelItemCount | number | 35 | Number of items in the reel (longer = longer spin feel). | | forcedTargetIndex | number | 30 | Index in reel where forcedResult is placed. | | onSpinStart | () => void | - | Called when spin starts. | | onSpinEnd | (result: T) => void | - | Called when reel stops with selected item. | | renderItem | (item, options) => ReactNode | - | Custom render per item (see below). | | itemClassName | string | - | Class for default item wrapper. | | itemStyle | CSSProperties | - | Style for default item wrapper. | | className | string | - | Root wrapper class. | | style | CSSProperties | - | Root wrapper style. | | overlayGradient | "none" \| "top-bottom" \| "left-right" | auto | Fade overlay; default by orientation. | | placeholderImage | string | "" | Image URL when item has no image. | | getItemImage | (item: T) => string | item => item.image | Resolve image URL from item. | | getItemName | (item: T) => string | item => item.name | Resolve name (e.g. alt text). |

Custom item style

• Simple: use itemClassName and itemStyle to style the default image wrapper.
• Full control: use renderItem to render each cell yourself. You receive (item, { isCenter, index, centerScale }) and return any ReactNode. The component handles position and animation; you control content and style.

<SlotMachine
  items={items}
  itemClassName="rounded-lg shadow-md"
  itemStyle={{ border: "2px solid gold" }}
/>

<SlotMachine
  items={items}
  renderItem={(item, { isCenter, centerScale }) => (
    <div style={{ transform: `scale(${isCenter ? centerScale : 1})` }}>
      <img src={item.image} alt={item.name} />
      {isCenter && <span className="badge">Selected</span>}
    </div>
  )}
/>

Responsive behavior

• Root wrapper is width: 100%, height: 100%, and uses containerType: "size" so you can size it from a parent (e.g. flex, grid, or fixed height).
• If you don’t pass itemSize, the component uses a default and adjusts with container size (ResizeObserver). For full control, pass itemSize from your own breakpoints or layout.

Example: full-width row of reels that scales with viewport:

<div className="slot-grid" style={{
  display: "flex",
  gap: "clamp(4px, 1vw, 16px)",
  width: "100%",
  height: "clamp(200px, 40vmin, 450px)",
}}>
  {reels.map((_, i) => (
    <div key={i} style={{ flex: 1, minWidth: 0 }}>
      <SlotMachine items={items} />
    </div>
  ))}
</div>

Types

• SlotItem: { id: string; image: string; name?: string; [key: string]: unknown }. Extend this in your app (e.g. add price, rarity).
• SlotMachineHandle: { spin: () => void } for imperative spin.
• SlotMachineProps<T>: props type; T must extend SlotItem.
• SlotItemRenderOptions: { isCenter: boolean; index: number; centerScale: number } passed to renderItem.

License

MIT