jbmui

Tear

  • UI Bits
  • adjustable

A sheet torn into strips along seams: controlled progress moves each strip to its own destination, with frayed, seeded edges at every seam.

Seams3 seams · 4 strips · the register's seams
Fray seedseed 1

Install

npx shadcn@latest add @jbm/tear

Needs the @jbm entry in components.json; see Install once.

Also installs @jbm/tokens, @jbm/paper, @jbm/register.

Docs

Usage

A long page tearing into four register strips
import { Tear } from "@/jbm/ui/tear"// progress comes from your timeline, e.g. interpolate(frame, [0, 45], [0, 1]).<Tear  w={520}  h={760}  seams={[190, 380, 570]}  progress={0.6}  stagger={0.1}  pieces={[    { to: { x: -40, y: -70, rotate: -5 } },    { to: { x: 36, y: -24, rotate: 3 } },    { to: { x: -30, y: 24, rotate: -2 } },    { to: { x: 34, y: 72, rotate: 3 } },  ]}>  {({ index, top }) => (    <div style={{ position: "absolute", left: 40, top: top + 32 }}>strip {index + 1}</div>  )}</Tear>
Continue a Paper's starting tear
import { Paper } from "@/jbm/ui/paper"import { sheetRadius } from "@/jbm/ui/register"import { Tear } from "@/jbm/ui/tear"// The same seed, seam, and width give the same frayed edge in both; Tear defaults to the sheetRadius(w) corner.export function Page({ torn }: { torn: boolean }) {  return torn ? (    <Tear w={520} h={760} seams={[380]} progress={0.4} pieces={[{ to: { y: -40, rotate: -3 } }, { to: { y: 40, rotate: 4 } }]} />  ) : (    <Paper w={520} h={760} radius={sheetRadius(520)} tension={1} seam={380} />  )}

API

Stage
fluid

The root is exactly w × h stage px, the size of the whole sheet; strips move by their destinations beyond it without changing layout. tearBounds(props) returns the box, relative to the root, that every strip and its shadow stays inside at any progress; give the stage at least that. The gallery sizes its stage as the union of tearBounds over every seam count it offers (a 520 × 760 sheet on a stage about 640 × 1000), so no strip or shadow is ever clipped.

Tearcomponent

A w × h Paper-style sheet cut at seams into strips. At progress 0 the strips tile the sheet exactly and no seam shows; as progress rises each strip parts from its neighbours and then drifts and turns toward its destination (tearMotion), its frayed seam edges fade in over its first 5% of travel, and the sheet's shadow hands over to per-strip shadows. A seam that has not opened yet shows no line and no shadow, even while other strips move. Writing is laid out once on the whole sheet and clipped to each strip. Strips travel past the w × h root: reserve tearBounds. Pure React, controlled, and deterministic per frame.

PropTypeDefaultDescription
wnumberrequiredSheet width in stage px.
hnumberrequiredSheet height in stage px.
seamsnumber[]requiredSeam y positions in stage px from the top; n usable seams make n + 1 strips. Non-finite values, seams closer than frayReach(fray) + 4 to an edge, and seams closer than twice that to the previous seam are dropped (see tearSeams).
progressnumberrequired0 = the whole sheet, 1 = every strip at its destination. Clamped and not eased; ease it yourself.
piecesTearPiece[][]Destinations top to bottom: { to: { x, y, rotate } }, an offset in stage px from the strip's place in the whole sheet and a turn in degrees about the strip's centre. A missing entry or field stays put. y follows the strip's progress and x and rotate its square (tearMotion). With a stagger, give every strip but the last a y at or above the one below it (the last may move down), so no strip slides back into its neighbour.
staggernumber0Delay between strips as a share of progress: strip i starts at i × stagger and all finish at 1. Capped at 0.9 / (strips − 1).
seednumber1Fray pattern. Paper's starting tear with the same seed, seam y, and w follows the same edge.
fraynumberFRAYFray amplitude in stage px (default FRAY, 6); edges stay within 1.8 × fray of the seam.
tonePaperTone"paper""paper" (card fill, ink edge), "accent", or "ink", as in Paper.
radiusnumbernoneCorner radius of the sheet's four outer corners in stage px; strips keep square corners at seams. Default sheetRadius(w) from Register (6 px on a 360 px sheet, 6 × w / 360, at least 4), so a torn page keeps the corners of the Register sheet it was.
edgebooleantrueDraws the shared outline (stroke.outline) on straight edges and, once torn, on frayed edges.
shadowbooleantruePaper shadow for the sheet and then each strip.
childrenReactNode | ((piece: TearPieceInfo) => ReactNode)noneThe sheet's writing on the whole w × h sheet, clipped to each strip. A node is repeated in every strip; a function ({ index, top, bottom, progress }) => node is called per strip (coordinates are the sheet's). Copies after the first strip are aria-hidden.
contentStyleCSSPropertiesnoneStyles for the w × h content layer each strip clips, for padding or layout.
styleCSSPropertiesnoneInline styles merged onto the w × h root.

tearGeometryfunction

Outlines for every strip in sheet coordinates. Neighbouring strips share the identical frayed polyline, so together they cover the sheet exactly; with an edge the straight sides sit half the shared outline (1.5px) in, on the centreline of Paper's border.

ParamTypeDefaultDescription
wnumberrequiredSheet width in stage px.
hnumberrequiredSheet height in stage px.
seamsnumber[]requiredSeam y positions; filtered by tearSeams.
seednumber1Fray pattern; default 1.
fraynumberFRAYFray amplitude; default FRAY.
radiusnumbernoneOuter corner radius; default sheetRadius(w), Register's sheet corner.
edgebooleantrueInsets the straight sides by half the shared outline, on its centreline; default true.

Returns One { index, top, bottom, outline, edges, seamAbove, seamBelow, center } per strip: SVG path data for the closed outline, the straight edges, and each frayed seam (null at the sheet's top or bottom), plus the rotation centre.

tearMotionfunction

Where a strip is at its own progress: it parts along the seam first and drifts and turns as it travels, so the two torn edges of a seam separate as parallel copies and never cross while close.

ParamTypeDefaultDescription
toTearDestination{}The strip's destination { x?, y?, rotate? }.
progressnumberrequiredThe strip's own 0–1 progress (tearPieceProgress); clamped.

Returns { x, y, rotate }: to.x × p², to.y × p, to.rotate × p².

tearBoundsfunction

The box every strip, and with shadow its shadow, stays inside at every progress, in the sheet's px (origin at its top-left, so x and y can be negative). Tear's root is only w × h; reserve this box around it.

ParamTypeDefaultDescription
wnumberrequiredSheet width in stage px, as passed to Tear.
hnumberrequiredSheet height in stage px.
seamsnumber[]requiredSeam y positions; filtered by tearSeams.
piecesTearPiece[][]The strips' destinations, as passed to Tear.
fraynumberFRAYFray amplitude; default FRAY.
shadowbooleantrueIncludes the shadows' room (default true): 16px at the sides, 8px above, and 34px below.

Returns { x, y, w, h } in stage px.

tearSeamsfunction

The seams Tear uses, from the ones you pass.

ParamTypeDefaultDescription
hnumberrequiredSheet height in stage px.
seamsnumber[]requiredCandidate seam y positions.
fraynumberFRAYFray amplitude; default FRAY.

Returns Finite seams, sorted, at least frayReach(fray) + 4 inside the sheet and at least twice that apart, so frayed edges never cross each other or the sheet's edge.

tearPieceProgressfunction

One strip's own travel after stagger.

ParamTypeDefaultDescription
progressnumberrequired0–1 overall progress.
indexnumberrequiredStrip index, top to bottom.
countnumberrequiredNumber of strips.
staggernumber0Share of progress between strip starts; default 0.

Returns 0–1: clamp((progress − index × stagger) / (1 − stagger × (count − 1))).

TearPropstype

Props of Tear.

TearPiecetype

{ to?: TearDestination }, one entry of pieces.

TearDestinationtype

{ x?: number; y?: number; rotate?: number }: offset in stage px and turn in degrees.

TearPieceInfotype

{ index, top, bottom, progress }, what a render-prop child receives per strip.

TearGeometrytype

One strip from tearGeometry.

QA checks

  • At Tear 0 the sheet must look whole: no seam line, hairline, or shadow between strips. Compare it with a plain Paper of the same size and radius.
  • Drag Tear through 0.02, 0.05, 0.5, and 1: seam edges fade in as the strips part, each strip keeps its frayed edges, and later strips overlap earlier ones.
  • At 8× zoom check where a frayed seam meets a straight side: the lines join on one centreline with the same 2px width, and each seam side is one clean frayed edge of irregular grain, not a regular zig-zag or two offset rows of teeth.
  • Drag Tear through 0.03 and 0.1 with Stagger 0.1 and 0.3: the parting strips' torn edges run as parallel copies and never cross, and the seams that have not opened yet show no line or shadow; the sheet's straight sides stay unbroken there.
  • Step Seams from 1 to 4 and Fray seed from 1 to 9: seams run only through clear rows of the page (a fray reach from every bar, header, numeral, and chevron, 8px from every box edge and table rule), so no torn edge cuts a table header or a bar into a black zig-zag or grazes a rule, frayed edges never cross each other or the sheet's edge, the pattern changes only with the seed, and every strip and shadow stays inside the stage.
  • Set Stagger to 0 and 0.3: every strip still reaches its destination at progress 1.