React Native Prize Wheel 🎡

A highly customizable, performant, and visually appealing wheel of fortune component for React Native applications. Perfect for games, promotions, and interactive experiences.

Features ✨

• 🎨 Fully Customizable - Colors, sizes, text, and more
• 🎯 Flexible Winner Selection - Probability-based OR predetermined winner
• 🎮 External Control - Trigger spins from external buttons via ref
• 💡 Decorative Boundary - Optional lights/boundary around wheel
• 📱 Cross-Platform - Works on iOS, Android, and Web (via Expo)
• ⚡ Performant - Smooth 60 FPS animations using native driver
• 📦 Lightweight - Minimal dependencies
• 🎭 TypeScript Support - Full type definitions included

Installation

npm install react-native-prize-wheel
# or
yarn add react-native-prize-wheel

Peer Dependencies

This package requires react-native-svg:

npm install react-native-svg
# or
yarn add react-native-svg

For Expo projects:

expo install react-native-svg

Basic Usage

import React from 'react';
import { View } from 'react-native';
import WheelOfFortune from 'react-native-prize-wheel';

const rewards = [
  { id: 1, label: '100 Coins', value: 100, color: '#FFD700' },
  { id: 2, label: '50 Coins', value: 50, color: '#C0C0C0' },
  { id: 3, label: '200 Coins', value: 200, color: '#FF6B6B' },
  { id: 4, label: '10 Coins', value: 10, color: '#4ECDC4' },
  { id: 5, label: '500 Coins', value: 500, color: '#95E1D3' },
  { id: 6, label: 'Try Again', value: 0, color: '#F38181' },
];

function App() {
  const handleSpinEnd = (reward) => {
    console.log('Won:', reward);
    alert(`You won ${reward.label}!`);
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <WheelOfFortune
        rewards={rewards}
        onSpinEnd={handleSpinEnd}
      />
    </View>
  );
}

export default App;

Advanced Usage

With Probability Weights

const rewards = [
  { id: 1, label: '100 Coins', value: 100, probability: 2 },    // 2x more likely
  { id: 2, label: '50 Coins', value: 50, probability: 3 },      // 3x more likely
  { id: 3, label: '500 Coins', value: 500, probability: 0.5 },  // Rare (0.5x)
  { id: 4, label: '10 Coins', value: 10, probability: 4 },      // 4x more likely
];

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={handleSpinEnd}
/>

With Adaptive Sizing (Recommended)

The wheel automatically fills its parent container width and maintains a 1:1 aspect ratio:

<View style={{ width: '80%' }}>
  <WheelOfFortune
    rewards={rewards}
    onSpinEnd={handleSpinEnd}
    // size="auto" is default - fills parent width with square aspect ratio
    // maxSize={400} is default - prevents wheel from being too large
  />
</View>

Or set a fixed size:

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={handleSpinEnd}
  size={300}  // Fixed 300x300 pixels
/>

With Predetermined Winner (Server-Controlled)

const [winnerIndex, setWinnerIndex] = useState(null);

// Fetch winner from backend
const fetchWinner = async () => {
  const response = await api.getSpinWinner();
  setWinnerIndex(response.winnerIndex); // 0 = first reward, 1 = second, etc.
};

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={handleSpinEnd}
  winnerIndex={winnerIndex}  // Overrides probability
/>

With External Spin Button

import { useRef } from 'react';
import { TouchableOpacity, Text } from 'react-native';

const wheelRef = useRef(null);

<WheelOfFortune
  ref={wheelRef}
  rewards={rewards}
  onSpinEnd={handleSpinEnd}
  tapToSpin={false}  // Disable tap-to-spin, use external button
/>

<TouchableOpacity onPress={() => wheelRef.current?.spin()}>
  <Text>Spin the Wheel!</Text>
</TouchableOpacity>

Custom Styling

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={handleSpinEnd}
  size={400}
  borderWidth={15}
  borderColor="#2C3E50"
  textSize={18}
  textColor="#FFFFFF"
  duration={5000}
  centerBackgroundColor="#E74C3C"
  centerTextColor="#FFFFFF"
  showBoundary={true}
  lightCount={24}
  lightColor="#FFD700"
/>

With Callbacks

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={(reward) => {
    console.log('Spin ended:', reward);
    // Update user balance, show modal, etc.
  }}
  onSpinStart={() => {
    console.log('Spin started!');
    // Disable other UI elements, play sound, etc.
  }}
  onSpinning={(angle) => {
    console.log('Current angle:', angle);
    // Track spinning progress
  }}
/>

Props

Required Props

| Prop | Type | Description | |------|------|-------------| | rewards | Reward[] | Array of reward objects | | onSpinEnd | (reward: Reward) => void | Callback when spin completes |

Optional Props - Winner Selection

| Prop | Type | Default | Description | |------|------|---------|-------------| | winnerIndex | number \| null | null | Predetermined winner index (0-based). Overrides probability when set. |

Optional Props - Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | number \| 'auto' | 'auto' | Wheel diameter in pixels, or 'auto' to fill parent width (maintains 1:1 aspect ratio) | | maxSize | number | 400 | Maximum size when using size='auto' | | borderWidth | number | 0 | Border thickness around wheel | | borderColor | string | '#1A1A1A' | Border color around wheel | | textColor | string | '#000000' | Default text color for segments | | textSize | number | 16 | Font size for segment text |

Optional Props - Behavior

| Prop | Type | Default | Description | |------|------|---------|-------------| | duration | number | 4000 | Spin duration in milliseconds | | disabled | boolean | false | Disable spinning |

Optional Props - Boundary/Lights

| Prop | Type | Default | Description | |------|------|---------|-------------| | showBoundary | boolean | true | Show decorative boundary with lights | | lightCount | number | 20 | Number of lights around boundary | | lightSize | number | 6 | Size of each light | | boundaryColor | string | '#2D3748' | Color of boundary ring | | lightColor | string | '#FFD700' | Color of lights | | boundaryThickness | number | 12 | Thickness of boundary ring | | boundaryOffset | number | 8 | Space between wheel and boundary |

Optional Props - Center Interaction

| Prop | Type | Default | Description | |------|------|---------|-------------| | tapToSpin | boolean | true | Enable tap-to-spin on center. Set to false when using external button. | | centerBackgroundColor | string | '#FFFFFF' | Background color of center circle | | centerTextColor | string | '#000000' | Text color of center ("SPIN"/"WAIT") |

Optional Props - Callbacks

| Prop | Type | Description | |------|------|-------------| | onSpinStart | () => void | Called when spin starts | | onSpinning | (angle: number) => void | Called during spinning with current angle |

Reward Object

interface Reward {
  id: string | number;        // Unique identifier
  label: string;              // Display text on segment
  value: any;                 // Reward value (coins, items, etc.)
  color?: string;             // Segment color (auto-generated if not provided)
  textColor?: string;         // Override default text color
  icon?: ReactNode;           // Optional icon/image (future feature)
  probability?: number;       // Weight for winning (default: 1). Ignored if winnerIndex is set.
}

Ref Methods

When using ref, the following methods are available:

interface WheelOfFortuneRef {
  spin: () => void;  // Trigger a spin programmatically
}

Examples

Disable After Spin

const [canSpin, setCanSpin] = useState(true);

<WheelOfFortune
  rewards={rewards}
  onSpinEnd={(reward) => {
    handleReward(reward);
    setCanSpin(false);
    // Re-enable after cooldown
    setTimeout(() => setCanSpin(true), 60000);
  }}
  disabled={!canSpin}
/>

Advanced: Custom Implementation

You can use the exported utilities and hooks to build custom wheel implementations:

import { 
  useWheelAnimation, 
  WheelSegment, 
  selectRewardByProbability 
} from 'react-native-prize-wheel';

// Build your custom wheel component

Performance Tips

1. Use useMemo for rewards array if it's dynamically generated
2. Keep reward count reasonable (6-12 segments optimal)
3. Use useNativeDriver: true (enabled by default)
4. Avoid heavy computations in callbacks

Troubleshooting

Wheel not rendering

• Ensure react-native-svg is installed
• Check that rewards array is not empty
• Verify all required props are provided

Animation not smooth

• Ensure useNativeDriver: true is enabled (default)
• Reduce wheel size if on low-end devices
• Check for heavy operations in callbacks

Contributing

Contributions are welcome! Please open an issue or submit a PR.

License

MIT