drop-spinner

A lightweight library to randomly pick an item from a list, with a visual "drop" animation! Use it as a utility function or as a reusable Web Component, with no framework dependencies.

Installation

# Install via npm

Usage as a function (TypeScript/JavaScript)

import { dropSpinner } from 'drop-spinner';

const items = ['🍎', '🍌', '🍇', '🍉'];
const picked = dropSpinner({
  items,
  animationSpeed: 1200, // optional
  circleSize: 220,      // optional
  onPick: (item) => {
    console.log('Picked!', item);
  }
});
console.log('Result:', picked);

Usage as a Web Component (plain HTML)

1. Include the script (compile to JS if using TypeScript):

<script type="module" src="./dist/DropSpinnerElement.js"></script>

2. Use the component in your HTML:

<drop-spinner
  items='["🍎","🍌","🍇","🍉"]'
  animation-speed="1000"
  circle-size="200"
></drop-spinner>

<script>
  const el = document.querySelector('drop-spinner');
  el.addEventListener('pick', e => {
    alert('Winner: ' + e.detail.item + '!');
  });
</script>

Minimal drop animation CSS

The animation is already included in the Web Component, but if you want to customize it:

.drop-anim {
  animation: drop-keyframes 1000ms cubic-bezier(.5,1.5,.5,1) forwards;
}
@keyframes drop-keyframes {
  0% { transform: translate(-50%, -100%); }
  100% { transform: translate(-50%, 80px); }
}

API

Interface DropSpinnerOptions

interface DropSpinnerOptions {
  items: string[]; // Items to pick from (text or image URLs)
  animationSpeed?: number; // ms, default 1000
  circleSize?: number;     // px, default 200
  onPick?: (item: string) => void; // optional callback
}

Build & typings

The package is ready to be built with tsup and will generate .d.ts typings automatically.

npm run build

License

MIT