Hooks and Animations API
This page covers the usePeel hook and animation utilities.
usePeel
1const {
2 peelRef,
3 animate,
4 reset,
5 setPosition,
6 getProgress,
7 stop,
8 isAnimating,
9} = usePeel();
How to Use It
usePeel gives you a ref plus helper methods. You attach peelRef to
PeelWrapper, then call the helpers from event handlers or effects.
1import { PeelWrapper, PeelTop, PeelBack, PeelBottom, usePeel } from "react-peel";
2
3function RevealCard() {
4 const { peelRef, animate, reset, isAnimating } = usePeel();
5
6 const handleReveal = async () => {
7 if (isAnimating()) return;
8 await animate({ to: { x: -80, y: -80 }, duration: 600, easing: "easeOut" });
9 };
10
11 return (
12 <>
13 <button onClick={handleReveal}>Reveal</button>
14 <button onClick={reset}>Reset</button>
15
16 <PeelWrapper ref={peelRef} height={200} width={200}>
17 <PeelTop style={{ backgroundColor: "#81afcb" }} />
18 <PeelBack style={{ backgroundColor: "#a0c7df" }} />
19 <PeelBottom style={{ backgroundColor: "#688394" }} />
20 </PeelWrapper>
21 </>
22 );
23}
Notes:
- The methods are no-ops until
peelRef.current is set (after mount).
reset() returns to the current corner position.- If you pass
preset or corner, those set the starting corner for resets.
Returned Values
| Property |
Type |
Description |
peelRef |
MutableRefObject |
Attach to PeelWrapper ref. |
animate |
(options) => Promise<void> |
Animate the peel position. |
reset |
() => void |
Reset peel to its corner. |
setPosition |
(x, y) => void |
Set peel position immediately. |
getProgress |
() => number |
Returns the clipped ratio (0 to 1). |
stop |
() => void |
Stop the current animation. |
isAnimating |
() => boolean |
Check if an animation is running. |
Animate Options
1await animate({
2 to: { x: 100, y: 100 },
3 from: { x: 200, y: 200 },
4 duration: 500,
5 easing: "easeOut",
6 onStart: () => {},
7 onEnd: () => {},
8 onProgress: (progress) => {},
9});
Supported easing names for usePeel.animate:
lineareaseIneaseOuteaseInOutspring
Common Patterns
Programmatic reveal based on user progress:
1<PeelWrapper
2 ref={peelRef}
3 drag
4 onPeelProgress={(progress) => {
5 if (progress > 0.6 && !isAnimating()) {
6 animate({ to: { x: 0, y: 0 }, duration: 250 });
7 }
8 }}
9>
10 ...
11</PeelWrapper>
Set the peel position directly (no animation):
easings
The utility easing set used by the lower-level animation helpers:
1import { easings } from "react-peel";
2
3// Available: linear, easeIn, easeOut, easeInOut,
4// easeInQuad, easeOutQuad, easeInOutQuad,
5// easeInExpo, easeOutExpo, spring, bounce, backOut
6const value = easings.easeOut(0.5);
animate
Generic value animator.
1import { animate } from "react-peel";
2
3const { stop, finished } = animate({
4 from: 0,
5 to: 100,
6 duration: 500,
7 easing: "easeOut",
8 onUpdate: (value) => console.log(value),
9 onComplete: () => console.log("done"),
10});
11
12await finished;
animatePeelPosition
Animate a peel instance directly.
1import { animatePeelPosition } from "react-peel";
2
3animatePeelPosition({
4 peel: peelRef.current,
5 from: { x: 200, y: 200 },
6 to: { x: 50, y: 50 },
7 duration: 600,
8 easing: "easeInOut",
9});
loopPeel
Loop an animation along a path.
1import { loopPeel } from "react-peel";
2
3const stop = loopPeel({
4 peel: peelRef.current,
5 path: [200, 200, -200, -200],
6 duration: 1000,
7 pingPong: true,
8});
9
10stop();
peelHint
Create a subtle peel hint.
1import { peelHint } from "react-peel";
2
3await peelHint(peelRef.current, {
4 peekSize: 30,
5 duration: 300,
6 repeat: 2,
7});
Types
1import type {
2 UsePeelReturn,
3 AnimatePeelOptions,
4 EasingName,
5 EasingFunction,
6 AnimateOptions,
7 AnimationController,
8 AnimatePeelPositionOptions,
9 LoopPeelOptions,
10} from "react-peel";
