API

Every prop, one page.

This is the flat reference — everything the compound API exposes, no clicking through tabs. For a live, interactive version of every prop, use the Storybook or the Playground.

import { RafflePick } from 'react-raffle-picker'

;<RafflePick items={['Alice', 'Bob', 'Carol']} inertia autoStart={false}>
  <RafflePick.Value animation="roll" />
  <RafflePick.Button startLabel="Draw" stopLabel="Stop" />
  <RafflePick.Countdown seconds={5} />
</RafflePick>

<RafflePick>

root

Owns the engine — cycling, phase machine, no-repeat history. Provides context; renders no DOM opinion beyond the wrapper element.

Prop	Type	Default	Notes
min, max	number	1, 100	Numeric range. Ignored if items is set.
items	string[]	—	Switches to item mode — cycles through names instead of numbers.
interval	number	100	Tick speed in ms, clamped to a minimum of 50.
random	boolean	true	Random pick per tick vs sequential increment.
inertia	boolean	false	Soft-start / soft-stop ramp instead of an instant flip.
autoStart	boolean	true	Begin cycling on mount.
noRepeat	boolean	true	Excludes previously frozen values from later rounds — no duplicate winners.
initialValue	number \| string	—	Value shown before the first run.
finalValue	number \| string	—	Forces settle to land on this value while the cycle still looks random.
onSelect	(value) => void	—	Fires once per round, when the phase settles to frozen.
onExhausted	() => void	—	Fires when start() runs but noRepeat has already drawn every candidate.
as	ElementType	'div'	Wrapper element/component.
className, style	string, CSSProperties	—	Wrapper class / inline style.
children	ReactNode	—	Compound sub-components — Value, Button, Countdown, Slots.

<RafflePick.Value>

consumer

Renders the cycling value. Writes textContent imperatively per tick — no React re-render while running. Multiple instances inside one root are supported.

Prop	Type	Default	Notes
animation	'roll' \| 'fade' \| 'blur' \| 'reel'	'roll'	Opt-in CSS animation, bound to the current tick duration.
as	ElementType	'span'	Rendered element.
className, style	string, CSSProperties	—	Class / inline style.

<RafflePick.Button>

consumer

Toggles start / freeze based on the current phase.

Prop	Type	Default	Notes
startLabel	ReactNode	—	Shown in idle / frozen — click starts a round.
stopLabel	ReactNode	—	Shown in running / starting — click stops.
waitLabel	ReactNode	—	Shown in settling. Button is disabled.
children	ReactNode	—	Fallback label when no state-specific label is set.
disabled	boolean	—	External disable, on top of the automatic disable during settling / when noRepeat is exhausted.
className, style	string, CSSProperties	—	Class / inline style.

<RafflePick.Countdown>

consumer

Schedules auto-freeze after seconds. Renders an SVG ring + numeric label by default.

Prop	Type	Default	Notes
seconds	number	—	Required. Auto-freeze delay. Renders only while running.
className, style	string, CSSProperties	—	Class / inline style.
children	(remaining: number) => ReactNode	—	Render-prop for fully custom output instead of the built-in ring + label.

<RafflePick.Slots>

consumer

Independent multi-reel slot machine. Each reel ticks on its own and stops with a stagger, left to right.

Prop	Type	Default	Notes
length	number	3	Number of independent reels.
chars	string	'0123456789'	Charset pool each reel picks from. Emoji-safe.
spinInterval	number	80	Tick rate per reel, ms, clamped ≥ 50.
staggerMs	number	220	Delay between consecutive reel stops on settle.
onResult	(joined: string) => void	—	Fires when the last reel lands, with the joined result.
className, slotClassName	string	—	Class for the row wrapper / each individual reel.
style, slotStyle	CSSProperties	—	Inline style for the row wrapper / each reel.

useRaffleContext()

escape hatch

For fully custom renderers. Must be called under <RafflePick> — throws otherwise.

Prop	Type	Default	Notes
phase	'idle' \| 'starting' \| 'running' \| 'settling' \| 'frozen'	—	Current state machine phase.
displayed	number \| string	—	Value to render post-freeze / pre-cycle.
noRepeat, exhausted, remaining	boolean, boolean, number	—	no-repeat pool state.
start, freeze, reset	() => void	—	Phase actions — start() is a no-op + fires onExhausted when the pool is empty.
resetHistory	() => void	—	Clears the noRepeat draw history without unmounting.
subscribe	(fn: (value: number) => void) => () => void	—	Tick subscription — for building fully custom renderers.

Exported types

typescript

Prop	Type	Default	Notes
RafflePickValue	number \| string	—	Value type used across value, onSelect, initialValue, finalValue.
AnimationType	'roll' \| 'fade' \| 'blur' \| 'reel'	—	Value animation kinds.
RafflePickPhase	'idle' \| 'starting' \| 'running' \| 'settling' \| 'frozen'	—	The phase state machine.
RaffleContextValue	object	—	Return type of useRaffleContext() — everything above.

Full prop docs, recipes, and CSS custom properties live in the README on GitHub.