react-native-jigsaw-puzzle 🧩

A fully customizable drag-and-drop Jigsaw Puzzle for React Native. No game engine. No shortcuts. Just React Native + SVG. 💪

Installation

npm install react-native-jigsaw-puzzle

Peer dependency: This library requires react-native-svg

npm install react-native-svg

Usage

Remote Image

import JigsawPuzzle from 'react-native-jigsaw-puzzle';

<JigsawPuzzle
  imageUrl="https://example.com/photo.jpg"
  cols={3}
  rows={3}
  cellSize={74}
  tabSize={12}
  onNext={() => console.log('Puzzle complete!')}
/>

Local Image

<JigsawPuzzle
  imageSource={require('./assets/photo.png')}
  cols={3}
  rows={3}
  onNext={() => console.log('Puzzle complete!')}
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onNext | () => void | required | Called when puzzle is completed and user taps Continue | | imageUrl | string | undefined | Remote image URL | | imageSource | any | undefined | Local image via require() | | cols | number | 3 | Number of columns in the grid | | rows | number | 3 | Number of rows in the grid | | cellSize | number | 74 | Size of each puzzle piece in pixels | | tabSize | number | 12 | Size of the interlocking tab/knob | | fallbackImages | string[] | picsum URLs | Fallback remote images when no image is provided |

Image Priority

imageSource (local) → imageUrl (remote) → fallbackImages[0]

Features

• ✅ Drag & drop with smooth spring animations
• ✅ Custom SVG jigsaw piece shapes
• ✅ Supports both remote URLs and local images
• ✅ Configurable grid size (2×2, 3×3, 4×4 etc.)
• ✅ Configurable piece size
• ✅ Snap detection with error & success feedback
• ✅ Progress badge (placed/total)
• ✅ Completion card with Continue button
• ✅ Works on Android & iOS

License

MIT © Ajith M