wrapType

Real DOM text on any 3D surface — sphere, cylinder, torus, or plane.

wrapType uses Three.js's CSS3DRenderer to distribute HTML text elements across the geometry of a 3D surface. Each character is a real DOM element oriented along the surface normal, which means variable fonts, CSS animations, hover states, and every other Liiift tool compose naturally — no canvas, no textures.

Install

npm install @liiift-studio/wraptype three

Three.js is a required peer dependency. React and React DOM are optional.

React

Component

import { WrapTypeScene } from '@liiift-studio/wraptype'

<WrapTypeScene
  text="Typography is the art and technique of arranging type"
  shape="sphere"
  fill="cover"
  fontSize={13}
  color="rgba(220,210,255,0.85)"
  autoRotate
  style={{ width: '100%', height: '500px' }}
/>

Hook

import { useWrapType } from '@liiift-studio/wraptype'

const { ref } = useWrapType({
  text: 'Typography is the art and technique of arranging type',
  shape: 'cylinder',
  fill: 'flow',
})

<div ref={ref} style={{ width: '100%', height: '500px' }} />

Vanilla JS

import { getCharPositions, createWrapScene } from '@liiift-studio/wraptype'

const container = document.getElementById('scene')

const positions = getCharPositions({
  text: 'Typography is the art and technique of arranging type',
  shape: 'torus',
  fill: 'cover',
})

const scene = createWrapScene(container, positions, {
  autoRotate: true,
  autoRotateSpeed: 0.6,
})

// Later, to clean up:
scene.destroy()

// Rebuild after changing options:
const newPositions = getCharPositions({ text: 'New text', shape: 'sphere' })
scene.rebuild(newPositions)

API

WrapTypeScene props / WrapTypeOptions

| Option | Type | Default | Description | |---|---|---|---| | text | string | — | Text to distribute across the surface. Repeats to fill. | | shape | 'sphere' \| 'cylinder' \| 'torus' \| 'plane' | 'sphere' | 3D geometry to wrap text onto. | | fill | 'cover' \| 'flow' \| 'full-width' \| 'full-height' | 'cover' | How to distribute characters across the surface. | | fontSize | number | 14 | Character font size in px. | | color | string | '#fff' | CSS color applied to every character element. | | fontFamily | string | undefined | CSS font-family override. | | radius | number | 300 | Surface radius in scene units. | | height | number | radius * 2 | Cylinder or plane height in scene units. | | autoRotate | boolean | false | Continuously rotate the scene. | | autoRotateSpeed | number | 1.0 | Rotation speed multiplier. | | camera | 'orbit' \| 'fixed' | 'orbit' | 'orbit' — drag to rotate, scroll to zoom. 'fixed' — static camera. | | cameraPosition | [number, number, number] | [0, 0, 900] | Initial camera position in scene units. | | charAdvanceRatio | number | 0.62 | Fraction of fontSize used as character advance width. | | lineHeightRatio | number | 1.4 | Line height multiplier relative to fontSize. | | style | CSSProperties | — | Applied to the container div. (React only) |

Fill modes

• cover — tiles the full surface, latitude bands scaled by circumference
• flow — a single band around the equator / circumference, text repeats
• full-width — one horizontal pass at the widest point of the shape
• full-height — one vertical pass from pole to pole

SceneHandle

Returned by createWrapScene():

| Method | Description | |---|---| | destroy() | Removes the renderer and all event listeners. | | rebuild(positions) | Replaces all character elements without rebuilding the renderer. |

getCharPositions(opts)

Returns CharPosition[] — one entry per character instance placed on the surface.

interface CharPosition {
  char: string
  position: [number, number, number]  // world position
  normal:   [number, number, number]  // outward surface normal
  right:    [number, number, number]  // tangent along text direction
  up:       [number, number, number]  // tangent perpendicular to right
}

How it works

Three.js's CSS3DRenderer maps HTML elements into 3D space using CSS perspective and matrix3d transforms. wrapType computes character positions analytically from the shape's surface equations — no UV unwrapping or texture atlases.

Each character element is oriented so its visible face points along the outward surface normal using a rotation matrix built from the surface's local right/up/normal frame.

OrbitControls are wired to a transparent overlay <div> so that pointer events reach the controls without selecting text.

Shapes

| Shape | Notes | |---|---| | Sphere | Latitude bands from φ = 0.12π to 0.88π. Band character count scales with sin(φ). | | Cylinder | Characters arc around the circumference, stacked in rows. | | Torus | Characters follow the outer ring parameterised by major and minor angle. | | Plane | Grid of characters on a flat surface facing the camera. |

Current version: v1.0.1