KQ-1890 · HANGING/SCROLL

Hanging Scroll

A vertical gallery mounted on a long paper scroll hung from a turned rod: as its scroll container scrolls, the stage pins and the paper rolls up onto the rod, bowing off the wall before the roll while each picture bends over the front of it, foreshortening and darkening as it turns away, and the knobs on the rod turn exactly with the rolled length as the roll fattens. The shown progress follows the scroll on a critically damped spring with the glide constants, and the hanging part is a lightly damped pendulum that the roll's changes of speed kick into a slight sway, swinging quicker as the scroll shortens until the weighted bottom bar rises with the last picture. Down, Page Down and Space roll to the next picture, Up and Page Up back, and Home and End jump to either end.

KQ-1890 · HANGING/SCROLL

Waylight Gallery · Winter room

Five views of the Coldbrook valley on one scroll. Read down; it rolls away above you.

Ink and wash on paper, mounted in the old way. The room is open until dusk; the scroll is rolled each evening and hung again at nine.

picture 1 of 5 · mountains in mist · 0%

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/hanging-scroll

Props

items: { src?: string; alt: string; caption?: string }[]; default defaultScrollItems; The pictures, top to bottom; the default is five ink-wash views drawn in code.
curl: number; default 0.5; How far the paper bows out before it meets the roll, 0 (straight into a tight roll) to 1 (a wide lifted curl).
rodSize: number; default 16; Diameter of the top rod in px, 10 to 28: a slim rod bends the pictures sharply, a thick roller slowly.
paperTone: "rice" | "silk" | "kraft" | "indigo"; default "rice"; The paper the pictures are mounted on.
mount: string; default —; Colour of the mounting bands and borders, any CSS colour; defaults to the tone's own.
sway: number; default 0.5; How much the weighted bottom bar swings as the roll speeds up and slows, 0 to 1.
range: number; default 320; Scroll distance from one picture to the next, px.
height: number; default 520; Height of the pinned stage, px; give it the height of the scroll container it sits in.
cord: boolean; default true; Hang the rod from a cord and a nail.
onIndexChange: (index: number) => void; default —; Fires with the picture at the reading line, from the scroll or key that moved it.
onProgressChange: (progress: number) => void; default —; Fires as the paper rolls, 0 (all hanging) to 1 (rolled to the last picture).
label: string; default "Hanging scroll"; Names the scroll for assistive technology.
dpr: number; default 2; Cap on the canvas's device pixel ratio, at most 2.
className: string; default —; Classes for the section.

Prop	Type	Default	Description
items	{ src?: string; alt: string; caption?: string }[]	defaultScrollItems	The pictures, top to bottom; the default is five ink-wash views drawn in code.
curl	number	0.5	How far the paper bows out before it meets the roll, 0 (straight into a tight roll) to 1 (a wide lifted curl).
rodSize	number	16	Diameter of the top rod in px, 10 to 28: a slim rod bends the pictures sharply, a thick roller slowly.
paperTone	"rice" \| "silk" \| "kraft" \| "indigo"	"rice"	The paper the pictures are mounted on.
mount	string	—	Colour of the mounting bands and borders, any CSS colour; defaults to the tone's own.
sway	number	0.5	How much the weighted bottom bar swings as the roll speeds up and slows, 0 to 1.
range	number	320	Scroll distance from one picture to the next, px.
height	number	520	Height of the pinned stage, px; give it the height of the scroll container it sits in.
cord	boolean	true	Hang the rod from a cord and a nail.
onIndexChange	(index: number) => void	—	Fires with the picture at the reading line, from the scroll or key that moved it.
onProgressChange	(progress: number) => void	—	Fires as the paper rolls, 0 (all hanging) to 1 (rolled to the last picture).
label	string	"Hanging scroll"	Names the scroll for assistive technology.
dpr	number	2	Cap on the canvas's device pixel ratio, at most 2.
className	string	—	Classes for the section.