Skip to content

Commit b2d2666

Browse files
author
Jan Fischer
committed
docs: update docz
1 parent 8a9b8c0 commit b2d2666

File tree

8 files changed

+279
-30
lines changed

8 files changed

+279
-30
lines changed

‎packages/docz/doczrc.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,15 @@ export default {
99
'Introduction',
1010
{
1111
name: 'Components',
12-
menu: ['Tween', 'Timeline', 'Reveal', 'SplitChars', 'SplitWords', 'Controls'],
12+
menu: [
13+
'Tween',
14+
'Timeline',
15+
'ScrollTrigger',
16+
'Reveal',
17+
'SplitChars',
18+
'SplitWords',
19+
'Controls',
20+
],
1321
},
1422
{ name: 'Plugins', menu: ['GSAP Plugins', 'CountPlugin', 'SvgDrawPlugin'] },
1523
'Instructions',

‎packages/docz/src/components/Controls.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,14 @@ Just wrap it around a Tween or Timeline component and you'll get control buttons
1515

1616
With the optional `playState` prop you can set an initial play state.
1717

18-
You can use the `PlayState` enum/object or just the strings "play", "reverse", "stop" or "pause".
18+
You can use the `PlayState` enum/object or just the strings "play", "restart", "reverse", "restartReverse", "stop", "stopEnd", "pause" or "resume".
1919

2020
import { Controls, PlayState, Tween } from 'react-gsap';
2121

2222
### Usage with Tween
2323

2424
<Playground>
25-
<Controls playState={PlayState.reverse}>
25+
<Controls playState={PlayState.restartReverse}>
2626
<Tween to={{ x: '200px', rotation: 180 }} duration={2} ease="back.out(1.7)">
2727
<div style={{ width: '100px', height: '100px', background: '#ccc' }} />
2828
</Tween>

‎packages/docz/src/components/Reveal.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ If no trigger is passed, the first element from any child Tween or Timeline that
8888

8989
## forwardRef trigger
9090

91-
You also can create a forwardRef component as trigger if you need a more complex wrapper or trigger.
91+
You can also create a forwardRef component as trigger if you need a more complex wrapper or trigger.
9292

9393
```javascript
9494
export const AnimationTrigger = React.forwardRef<HTMLDivElement>(({ children }, ref) => (

‎packages/docz/src/components/ScrollTrigger.mdx‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
name: ScrollTrigger
3+
menu: Components
4+
---
5+
6+
import { Fragment } from 'react';
7+
import { Playground, Props } from 'docz'
8+
import { Controls, PlayState, ScrollTrigger } from './../../../react-gsap/src/'
9+
import { Tween } from './Tween'
10+
import { Timeline, TargetWithNames } from './Timeline'
11+
12+
# ScrollTrigger
13+
14+
The ScrollTrigger component is a small helper for the ScrollTrigger plugin.
15+
16+
Read the official documentation: https://greensock.com/docs/v3/Plugins/ScrollTrigger
17+
18+
It's available since version 3.2.0.
19+
Before you also could use the ScrollTrigger plugin by importing/registering and using it in a Tween or Timeline by yourself:
20+
21+
import { Tween } from 'react-gsap';
22+
23+
import { ScrollTrigger } from 'gsap/dist/ScrollTrigger';
24+
gsap.registerPlugin(ScrollTrigger);
25+
26+
<Tween
27+
to={{
28+
x: '300px',
29+
scrollTrigger: {
30+
trigger: '.square',
31+
start: '-200px center',
32+
end: '200px center',
33+
scrub: 0.5,
34+
markers: true,
35+
},
36+
}}
37+
>
38+
<div className="square" style={{ width: '100px', height: '100px', background: '#ccc' }} />
39+
</Tween>
40+
41+
## Basic usage
42+
43+
With the ScrollTrigger component, it looks like the following. If you don't add a trigger prop, it will use the ref from the Tween target.
44+
45+
<Playground>
46+
<ScrollTrigger
47+
start="-200px center"
48+
end="200px center"
49+
scrub={0.5}
50+
markers
51+
>
52+
<Tween
53+
to={{
54+
x: '300px',
55+
}}
56+
>
57+
<div style={{ width: '100px', height: '100px', background: '#ccc' }} />
58+
</Tween>
59+
<Tween
60+
to={{
61+
x: '300px',
62+
}}
63+
>
64+
<div style={{ width: '100px', height: '100px', background: '#999' }} />
65+
</Tween>
66+
</ScrollTrigger>
67+
</Playground>
68+
69+
## Use "trigger" prop
70+
71+
Currently it's not possible to change the props on the fly. **So this will not work for the `trigger` prop**:
72+
73+
const triggerRef = useRef(null);
74+
const [trigger, setTrigger] = useState(triggerRef.current);
75+
76+
useEffect(() => {
77+
setTrigger(triggerRef.current);
78+
}, []);
79+
80+
return (
81+
<>
82+
<ScrollTrigger trigger={trigger}>
83+
<Tween
84+
to={{
85+
x: '500px',
86+
}}
87+
>
88+
<div>This element gets not tweened by ref</div>
89+
</Tween>
90+
</ScrollTrigger>
91+
92+
<Square ref={triggerRef}>
93+
This element is the trigger
94+
</Square>
95+
</>
96+
);
97+
98+
If you want to target a ref directly instead of using a CSS selector you can use a Timeline with a forwardRef target:
99+
100+
// This is the target component which "exports" 4 refs
101+
const TargetWithNames = forwardRef((props, ref: any) => {
102+
const div1 = useRef(null);
103+
const div2 = useRef<MutableRefObject<any>[]>([]);
104+
const div3 = useRef(null);
105+
const trigger = useRef(null);
106+
107+
useImperativeHandle(ref, () => ({
108+
div1,
109+
div2,
110+
div3,
111+
trigger,
112+
}));
113+
114+
return (
115+
<div ref={trigger} style={{ textAlign: 'center' }}>
116+
<h3 ref={div1}>THIS</h3>
117+
<SplitChars
118+
ref={(charRef: MutableRefObject<any>) => div2.current.push(charRef)}
119+
wrapper={<h3 style={{ display: 'inline-block' }} />}
120+
>
121+
TEST
122+
</SplitChars>
123+
<h3 ref={div3}>IS A</h3>
124+
</div>
125+
);
126+
});
127+
128+
You can then use the key of the exported refs in the `trigger` or `target` props.
129+
If it doesn't find a ref with this key it will use the `trigger` string as CSS selector.
130+
131+
<Playground>
132+
<ScrollTrigger
133+
trigger="trigger"
134+
start="top center"
135+
end="400px center"
136+
scrub={0.5}
137+
markers={true}
138+
pin={true}
139+
>
140+
<Timeline target={<TargetWithNames />}>
141+
<Tween
142+
from={{
143+
x: '-100vw',
144+
}}
145+
target="div1"
146+
/>
147+
<Tween
148+
from={{
149+
x: '-100vw',
150+
}}
151+
target="div3"
152+
/>
153+
<Tween
154+
from={{
155+
x: '-100vw',
156+
}}
157+
stagger={0.5}
158+
target="div2"
159+
/>
160+
</Timeline>
161+
</ScrollTrigger>
162+
</Playground>
163+
164+
## Standalone
165+
166+
If you don't pass children to the component a GSAP ScrollTrigger instance will be created and can be used standalone.
167+
168+
You can get the instance by calling `getGSAP()` on the ref.
169+
170+
<Playground>
171+
{() => {
172+
const scrollTrigger = React.useRef(null);
173+
return (
174+
<Fragment>
175+
<div id="id" style={{width: '100px', height: '100px', background: '#ccc'}}/>
176+
<div id="otherID" style={{width: '100px', height: '100px', background: '#999'}}/>
177+
<ScrollTrigger
178+
ref={scrollTrigger}
179+
trigger="#id"
180+
start="top top"
181+
endTrigger="#otherID"
182+
end="bottom 50%+=100px"
183+
markers
184+
onToggle={self => console.log("toggled, isActive:", self.isActive)}
185+
onUpdate={self => {
186+
console.log("progress:", self.progress.toFixed(3), "direction:", self.direction, "velocity", self.getVelocity());
187+
}}
188+
/>
189+
<button onClick={() => scrollTrigger.current.getGSAP().disable()}>Disable ScrollTrigger</button>
190+
</Fragment>
191+
)
192+
}}
193+
</Playground>

‎packages/docz/src/components/Timeline.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,10 @@ More info: [https://greensock.com/docs/v3/GSAP/Timeline/addLabel()](https://gree
257257
| Field | As string |
258258
| :-- | :-- |
259259
| play | "play" |
260+
| restart | "restart" |
260261
| reverse | "reverse" |
262+
| restartReverse | "restartReverse" |
261263
| stop | "stop" |
264+
| stopEnd | "stopEnd" |
262265
| pause | "pause" |
266+
| resume | "resume" |

‎packages/docz/src/components/Timeline.tsx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,15 @@ const TargetWithNames = forwardRef((props, ref: any) => {
1616
const div1 = useRef(null);
1717
const div2 = useRef<MutableRefObject<any>[]>([]);
1818
const div3 = useRef(null);
19+
const trigger = useRef(null);
1920
useImperativeHandle(ref, () => ({
2021
div1,
2122
div2,
2223
div3,
24+
trigger,
2325
}));
2426
return (
25-
<div style={{ textAlign: 'center' }}>
27+
<div ref={trigger} style={{ textAlign: 'center' }}>
2628
<h3 ref={div1}>THIS</h3>
2729
<SplitChars
2830
ref={(charRef: MutableRefObject<any>) => div2.current.push(charRef)}

‎packages/docz/src/components/Tween.mdx‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -88,31 +88,6 @@ More info: https://greensock.com/docs/v3/Staggers
8888
</Controls>
8989
</Playground>
9090

91-
## Use playState and totalProgress props
92-
93-
With the playState and progress/totalProgress props you can control the Tween.
94-
So you don't need low-level access to play/reverse/pause/stop or seek to a position.
95-
96-
<Playground>
97-
{() => {
98-
const [playing, setPlaying] = React.useState(false)
99-
const [progress, setProgress] = React.useState(0)
100-
return (
101-
<Fragment>
102-
<Tween to={{ x: '200px' }} duration={2} playState={playing ? PlayState.play : PlayState.pause} totalProgress={progress}>
103-
<div style={{ width: '100px', height: '100px', background: '#ccc' }} />
104-
</Tween>
105-
<button onClick={() => setPlaying(!playing)}>
106-
{playing ? 'Pause' : 'Play'}
107-
</button>
108-
<div>
109-
<input type="range" max="1" step="0.001" value={progress} onChange={(event) => setProgress(event.target.value)} />
110-
</div>
111-
</Fragment>
112-
)
113-
}}
114-
</Playground>
115-
11691
## Props
11792

11893
The question mark means it's an optional prop.
@@ -159,6 +134,10 @@ More info: https://greensock.com/docs/v3/Staggers
159134
| Field | As string |
160135
| :-- | :-- |
161136
| play | "play" |
137+
| restart | "restart" |
162138
| reverse | "reverse" |
139+
| restartReverse | "restartReverse" |
163140
| stop | "stop" |
141+
| stopEnd | "stopEnd" |
164142
| pause | "pause" |
143+
| resume | "resume" |

‎packages/docz/src/instructions/PlayState.mdx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
name: Use "playState" prop
3+
menu: Instructions
4+
---
5+
6+
import { Fragment } from 'react';
7+
import { Playground } from 'docz'
8+
import { PlayState, Tween } from './../../../react-gsap/src/'
9+
10+
# Use playState and totalProgress props
11+
12+
With the playState and progress/totalProgress props you can control a Tween or a Timeline.
13+
So you don't need low-level access to play/reverse/pause/stop or seek to a position.
14+
15+
From version 3.2.0 on the `playState` prop also works for the initial state and the following states were added:
16+
`restartReverse`, `stopEnd`, `resume`.
17+
18+
The following gsap functions are called internally, if the `playState` prop change:
19+
20+
if (playState === PlayState.play) {
21+
gsap.play();
22+
} else if (playState === PlayState.restart) {
23+
gsap.restart(true);
24+
} else if (playState === PlayState.reverse) {
25+
gsap.reverse();
26+
} else if (playState === PlayState.restartReverse) {
27+
gsap.reverse(0);
28+
} else if (playState === PlayState.stop) {
29+
gsap.pause(0);
30+
} else if (playState === PlayState.stopEnd) {
31+
gsap.reverse(0);
32+
gsap.pause();
33+
} else if (playState === PlayState.pause) {
34+
gsap.pause();
35+
} else if (playState === PlayState.resume) {
36+
gsap.resume();
37+
}
38+
39+
<Playground>
40+
{() => {
41+
const [playState, setPlayState] = React.useState(PlayState.pause);
42+
const [totalProgress, setTotalProgress] = React.useState(0)
43+
return (
44+
<Fragment>
45+
<Tween to={{ x: '300px' }} duration={2} playState={playState} totalProgress={totalProgress}>
46+
<div style={{ width: '100px', height: '100px', background: '#ccc' }} />
47+
</Tween>
48+
<button onClick={() => setPlayState(PlayState.play)}>play</button>
49+
<button onClick={() => setPlayState(PlayState.restart)}>restart</button>
50+
<button onClick={() => setPlayState(PlayState.reverse)}>reverse</button>
51+
<button onClick={() => setPlayState(PlayState.restartReverse)}>restartReverse</button>
52+
<button onClick={() => setPlayState(PlayState.stop)}>stop</button>
53+
<button onClick={() => setPlayState(PlayState.stopEnd)}>stopEnd</button>
54+
<button onClick={() => setPlayState(PlayState.pause)}>pause</button>
55+
<button onClick={() => setPlayState(PlayState.resume)}>resume</button>
56+
<div>
57+
<input type="range" max="1" step="0.001" value={totalProgress} onChange={(event) => setTotalProgress(event.target.value)} />
58+
</div>
59+
</Fragment>
60+
)
61+
}}
62+
</Playground>
63+

0 commit comments

Comments
 (0)