3D Product Spin Viewer React component
A 360° product viewer driven by an image sequence: drag with inertia, an idle spin, a tick ruler that jumps to any angle, hotspots that fade in on the side they belong to, and pointer-follow zoom, with a hairline loading bar.
About the 3D Product Spin Viewer component
3D Product Spin Viewer lets shoppers turn a product all the way round. It plays a sequence of photos taken around the product, so dragging feels like turning the real thing; let go with a flick and it keeps spinning for a moment, then slows to a gentle idle turn.
A ruler of thin ticks under the product shows the angle and jumps to any view, hotspots appear on the side they describe (the lens on the front, the screen on the back), and tapping zooms in with the view following the pointer. The demo product is an unbranded camera rendered for this component.
When to use it
Use it on product pages for objects people want to inspect from every side: cameras, shoes, bags, watches, furniture, devices, packaging.
It needs a turntable sequence of the product (36 to 72 evenly spaced shots, ideally on a transparent or matching background); for a single hero image, a zoomable image is enough.
Installation
Add the 3D Product Spin Viewer component to your project with the shadcn CLI. It lands in components/product-spin-viewer.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/product-spin-viewerOr copy the source by hand and install its dependencies:
npm install clsx tailwind-mergeProps
<ProductSpinViewer /> accepts 15 props, all optional. It also accepts the usual <div> attributes, like className, style, id and aria-*, and passes them to its root element.
| Prop | Type | Default |
|---|---|---|
| frames Image sequence of one full turn, evenly spaced, in turning order. | string[] | DEFAULT_FRAMES |
| theme | "dark" | "light" | "dark" |
| height | number | 560 |
| title | string | "Field Camera 35" |
| subtitle | string | "Brushed aluminium · Leatherette" |
| autoSpin Idle spin in degrees per second; 0 turns it off. | number | 24 |
| dragSensitivity | number | 1 |
| inertia Keep turning for a moment after a flick. | boolean | true |
| reverse Turn the other way for the same drag. | boolean | false |
| hotspots | { angle: number; x: number; y: number; label: string; detail?: string }[] | DEFAULT_HOTSPOTS |
| showRuler | boolean | true |
| showHint | boolean | true |
- frames
Image sequence of one full turn, evenly spaced, in turning order.
string[]Default: DEFAULT_FRAMES - theme"dark" | "light"Default: "dark"
- heightnumberDefault: 560
- titlestringDefault: "Field Camera 35"
- subtitlestringDefault: "Brushed aluminium · Leatherette"
- autoSpin
Idle spin in degrees per second; 0 turns it off.
numberDefault: 24 - dragSensitivitynumberDefault: 1
- inertia
Keep turning for a moment after a flick.
booleanDefault: true - reverse
Turn the other way for the same drag.
booleanDefault: false - hotspots{ angle: number; x: number; y: number; label: string; detail?: string }[]Default: DEFAULT_HOTSPOTS
- showRulerbooleanDefault: true
- showHintbooleanDefault: true
Show all 15 propsShow fewer
| enableZoom | boolean | true |
| zoomScale | number | 1.9 |
| frameAspect Width / height of the frames. | number | 1.25 |
- enableZoombooleanDefault: true
- zoomScalenumberDefault: 1.9
- frameAspect
Width / height of the frames.
numberDefault: 1.25
Collections
Use-case pages that compare 3D Product Spin Viewer with the other components that do a similar job.
npm dependencies
Installed for you by the shadcn CLI.
3D Product Spin Viewer FAQ
- How many frames should I use?
- 36 frames (every 10°) is the usual minimum; 48 to 72 turn more smoothly. All frames load up front, so keep each one light (WebP around 15–30 KB).
- How do I place a hotspot?
- Give it the angle it belongs to and its x and y as percentages of the image at that angle. It fades in within about 28° of that angle.
- Can I turn off the idle spin?
- Yes, autoSpin={0}. Otherwise it is the speed in degrees per second (24 by default), paused while zoomed or while a hotspot is open.
- The product turns the wrong way when I drag.
- Pass reverse, or supply the frames in the opposite order.
- Do the frames need a transparent background?
- No, but transparent PNG or WebP frames sit cleanly on both the dark and light themes and let the soft floor shadow show.
