react-ball-studio

3D material ball components for React — generate stunning hardware-finish balls with full color control, export to PNG/SVG/JSON, and embed a live viewer anywhere.

Install

npm install react-ball-studio

Peer dependencies (must be in your project):

npm install react react-dom

All Three.js / r3f dependencies install automatically.

Components

BallMaker — Full Studio Editor

A complete material-ball studio with a control panel + 3D canvas. Drop it into a full-page layout.

import 'react-ball-studio/styles.css'
import { BallMaker } from 'react-ball-studio/maker'

export default function Page() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BallMaker />
    </div>
  )
}

Features:

• 12 hardware finish types (Chrome, Brushed, Gloss, Matte, Copper, Translucent…)
• 1–4 color palette with 6 blend modes (Solid, Gradient, Split, Swirl, Marble, Liquid)
• Sliders: Metalness, Roughness, Clearcoat, Sheen, Iridescence, Transmission, IOR, Glow
• Export: PNG (transparent), SVG (transparent), JSON config
• Import JSON config
• Save / load presets (localStorage)
• JSON Preview modal with live 3D viewer

BallViewer — Embed Anywhere

A lightweight read-only 3D viewer driven by a JSON config. Transparent background — composites over any page background.

import 'react-ball-studio/styles.css'
import { BallViewer } from 'react-ball-studio/viewer'

const config = {
  version: '1.0',
  material: {
    type: 'chrome',
    metalness: 1,
    roughness: 0.05,
    clearcoat: 1,
    clearcoatRoughness: 0.05,
    reflectivity: 1,
    transmission: 0,
    opacity: 1,
    sheen: 0,
    iridescence: 0,
    ior: 1.5,
    glow: 0,
  },
  colors: {
    palette: ['#d4d4d8'],
    fusion: 'solid',
  },
  autoRotate: true,
}

export default function MyPage() {
  return <BallViewer config={config} size={200} />
}

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | config | MaterialConfig \| MaterialExport | required | Material configuration | | size | number | 100 | Canvas size in px (always square) |

Behaviour:

• Transparent background — ball + shadow only
• Rotates on Y-axis only (drag to spin)
• Drop shadow included for visibility on light backgrounds
• Auto-adapts render quality on slow hardware

Types

import type {
  MaterialConfig,
  MaterialExport,
  MaterialType,
  FusionType,
  SavedPreset,
} from 'react-ball-studio'

MaterialType

'chrome' | 'brushed' | 'metallic_paint' | 'gloss' | 'matte' | 'satin' | 'powder_coat' | 'anodized' | 'copper' | 'rubber' | 'plastic' | 'translucent'

FusionType

'solid' | 'gradient' | 'split' | 'swirl' | 'marble' | 'liquid'

Hook — Custom UI

Use useMaterialConfig to build your own controls on top of the 3D ball:

import 'react-ball-studio/styles.css'
import { useMaterialConfig } from 'react-ball-studio'
import { BallViewer } from 'react-ball-studio/viewer'

export default function Custom() {
  const { config, updateConfig, applyMaterialType, exportJSON } = useMaterialConfig()

  return (
    <div>
      <BallViewer config={config} size={300} />
      <button onClick={() => applyMaterialType('copper')}>Copper</button>
      <button onClick={() => updateConfig('roughness', 0.8)}>Make Matte</button>
      <button onClick={exportJSON}>Export JSON</button>
    </div>
  )
}

Utilities

import {
  generateSVG,        // MaterialConfig → SVG string
  buildMaterialExport, // MaterialConfig → structured JSON
  parseJsonToConfig,  // raw JSON string → MaterialConfig
  generateColorTexture, // colors + fusion → THREE.CanvasTexture
  downloadFile,       // trigger browser file download
  MATERIAL_META,      // metadata for all 12 material types
  createDefaultConfig, // create default config for a material type
} from 'react-ball-studio'

Next.js Setup

// app/page.tsx
import 'react-ball-studio/styles.css'
import dynamic from 'next/dynamic'

const BallMaker = dynamic(
  () => import('react-ball-studio/maker').then(m => ({ default: m.BallMaker })),
  { ssr: false }
)

export default function Page() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BallMaker />
    </div>
  )
}

Why ssr: false? Three.js requires browser APIs (document, WebGL) that aren't available during server-side rendering.

JSON Format

The full export format from BallMaker → Export JSON:

{
  "version": "1.0",
  "generator": "3D Material Ball Studio",
  "created": "2026-01-01T00:00:00.000Z",
  "name": "Chrome Ball",
  "material": {
    "type": "chrome",
    "metalness": 1,
    "roughness": 0.05,
    "clearcoat": 1,
    "clearcoatRoughness": 0.05,
    "reflectivity": 1,
    "transmission": 0,
    "opacity": 1,
    "sheen": 0,
    "iridescence": 0,
    "ior": 1.5,
    "glow": 0
  },
  "colors": {
    "palette": ["#d4d4d8"],
    "fusion": "solid"
  },
  "autoRotate": true
}

Pass this directly to BallViewer as the config prop.

License

MIT