wrapType

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

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' | 'stool' | 'flag'	'sphere'	Built-in 3D geometry to wrap text onto.
mode	'surface' | 'silhouette'	'surface'	Surface mode places characters on the geometry; silhouette places them along the outline contour.
fill	'cover' | 'flow' | 'full-width' | 'full-height' | 'pattern'	'cover'	How to distribute characters across the surface.
fontSize	number	14	Character font size in px.
fontFamily	string	undefined	CSS font-family override applied to each character span.
fontWeight	string | number	'normal'	CSS font-weight applied to each character span.
color	string	'white'	CSS color applied to every character element.
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, 700]	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.
repeat	boolean	true	When false, text is placed exactly once without tiling.
characterCurve	number	0	Bend characters to follow surface curvature. 0 = flat, 1 = full bend.
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
• pattern — repeating tiled pattern with configurable gap

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
}

getCharPositionsAt(opts, t)

Like getCharPositions, but evaluates positions at a specific time parameter t — useful for animating the geometry.

isAnimatedShape(shape)

Returns true if the given shape name requires time-stepped updates (e.g. 'flag').

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.
Stool	Cylinder with disc caps — top, side, and bottom surfaces sampled separately.
Flag	Animated surface — characters follow a sinusoidal wave that propagates along the flag.

Custom meshes

Drop any .glb, .gltf, or .obj file onto the demo. wrapType samples the surface with MeshSurfaceSampler, orients each character along the local normal, and auto-scales to fit the scene radius.

---

Current version: 1.0.4