sticker-forge-react

React library for turning arbitrary JSX/Tailwind content into a realistic, peelable WebGL sticker.

The React adapter snapshots the cover automatically, then hands the resulting canvas directly to the framework-independent Sticker Forge renderer. Content revealed underneath remains normal, interactive React DOM.

Credits

The concept and WebGL peel implementation are inspired by CatsJuice/sticker-forge, released under the MIT License. See THIRD_PARTY_NOTICES.md for the retained attribution and license text.

Install

pnpm add sticker-forge-react

The package expects React 18 or newer. It is browser-only and intended for client-side React applications such as Vite.

Peel a React component

import { PeelableSticker } from "sticker-forge-react/react";

export function Ticket() {
  return (
    <PeelableSticker
      ariaLabel="ฉีกสติกเกอร์"
      interaction={{
        grabFrom: "left",
        peelToward: "right",
        threshold: 0.72,
      }}
      onPeelComplete={() => console.log("peeled")}
    >
      <div className="border-y-2 border-dashed bg-white p-6">
        เก็บ LV.เชี่ยวชาญ ให้ครบ เพื่อปลดล็อคห้องสอบ
      </div>
    </PeelableSticker>
  );
}

The child may use Tailwind, inline SVG, imported Vite assets, pseudo-elements, and web fonts. The cover is a visual snapshot while peeling, so controls that must remain interactive should be placed in the revealed content instead.

Reveal React content

import { PeelReveal } from "sticker-forge-react/react";

export function ExamRoom({ unlocked, unlock }: Props) {
  return (
    <PeelReveal
      revealed={unlocked}
      onReveal={unlock}
      cover={<LockedExamRoom />}
      stickerProps={{
        snapshotKey: `locked-${locale}-${completedCount}`,
        interaction: {
          grabFrom: "left",
          peelToward: "right",
          threshold: 0.72,
        },
        sound: { enabled: true, volume: 0.65 },
      }}
    >
      <ExamRoomActions />
    </PeelReveal>
  );
}

revealed is controlled by the application. Persist it in the backend or application state; Sticker Forge does not access storage or APIs.

Interaction

• grabFrom: "left" | "right" | "top" | "bottom" | "any"
• peelToward: "left" | "right" | "top" | "bottom" | "free"
• threshold: normalized completion threshold
• incomplete snap gestures spring back automatically
• Arrow keys adjust peel progress
• Enter or Space completes the peel
• motion: "system" respects prefers-reduced-motion

Sound is disabled by default.

Imperative handle

const sticker = useRef<PeelableStickerHandle>(null);

sticker.current?.reset();
await sticker.current?.recapture();
const state = sticker.current?.getState();

Use snapshotKey to refresh a cover when its content changes. Resize-driven snapshots are handled automatically and deferred until an active gesture ends.

For animated carousels or other transition-heavy screens, delay the initial snapshot/WebGL setup until the transition settles:

<PeelableSticker defer={350} pixelRatio={1}>
  <Ticket />
</PeelableSticker>

Image URLs use the browser cache during snapshots. Set cacheBust only when an asset changes at the same URL and must be downloaded again.

Core API

The renderer remains available without React:

import { createSticker } from "sticker-forge-react/core";

const instance = await createSticker(element, {
  source: { type: "image", src: imageUrl },
});

Call instance.destroy() before permanently removing its target.

Local development

pnpm install
pnpm dev
pnpm typecheck
pnpm test
pnpm build

The Vite/Tailwind playground includes the exam-room peel-to-reveal example.

Release

1. Update version in package.json.
2. Add release notes to CHANGELOG.md.
3. Run pnpm release:check.
4. Authenticate your npm account and enable security-key/passkey 2FA.
5. Run pnpm publish.

The package publishes publicly to the npm registry.

Only dist, license files, and third-party notices are included.