@th-batman/3d-viewer-react

Official React component wrapper for @th-batman/3d-viewer-core. Renders photorealistic 3D jewelry viewers, swatches, and customizers in Next.js, Remix, Vite, and standard React applications.

Installation

pnpm add @th-batman/3d-viewer-react @th-batman/3d-viewer-core three
# or with npm
npm install @th-batman/3d-viewer-react @th-batman/3d-viewer-core three

1. Turnkey Customizer (5-Line Embed)

The <JewelryCustomizer /> provides a complete, responsive 3D canvas and luxury swatch controls out of the box:

import { JewelryCustomizer } from '@th-batman/3d-viewer-react'

export function ProductPage() {
  return (
    <JewelryCustomizer
      src="https://cdn.example.com/models/solitaire-ring.glb"
      defaultMetal="yellow-gold-18k"
      defaultStone="diamond-d"
      height={520}
      autoRotate
      onMetalChange={(metal) => console.log('Selected metal:', metal)}
      onStoneChange={(stone) => console.log('Selected stone:', stone)}
    />
  )
}

2. Composable Primitives (<Viewer /> + Swatches)

Combine <Viewer /> with pre-built <MetalSwatches /> and <StoneSwatches /> for custom layouts:

import { useState } from 'react'
import {
  Viewer,
  MetalSwatches,
  StoneSwatches,
  type MetalColorProp,
  type StoneColorProp,
} from '@th-batman/3d-viewer-react'

export function Customizer() {
  const [metal, setMetal] = useState<MetalColorProp>('yellow-gold-18k')
  const [stone, setStone] = useState<StoneColorProp>('diamond-d')

  return (
    <div style={{ maxWidth: '840px', margin: '0 auto' }}>
      <Viewer
        src="https://cdn.example.com/models/solitaire-ring.glb"
        metalColor={metal}
        stoneColor={stone}
        height={500}
        autoRotate
      />

      <div style={{ marginTop: '16px', display: 'flex', flexDirection: 'column', gap: '14px' }}>
        <MetalSwatches value={metal} onChange={setMetal} variant="pills" />
        <StoneSwatches value={stone} onChange={setStone} variant="pills" />
      </div>
    </div>
  )
}

3. Headless Hook (useJewelryCustomizer)

For custom UI layouts with pre-wired state and preset lookup:

import { Viewer, useJewelryCustomizer } from '@th-batman/3d-viewer-react'

export function HeadlessCustomizer() {
  const { metal, setMetal, stone, setStone, metalOptions, stoneOptions, viewerProps } =
    useJewelryCustomizer({
      defaultMetal: 'yellow-gold-18k',
      defaultStone: 'diamond-d',
    })

  return (
    <div>
      <Viewer src="/models/ring.glb" {...viewerProps} height={480} />
      {/* Build your bespoke buttons, dropdowns, or swatches */}
    </div>
  )
}

License

MIT