Skip to content

Commit f876a4e

Browse files
jscottsmithjscottsmith
committed
docs: add parallax props documentation
1 parent f4a6e39 commit f876a4e

File tree

7 files changed

+216
-10
lines changed

7 files changed

+216
-10
lines changed

‎documentation/docs/examples/advanced-banners.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,6 @@ const Component = () => {
7777

7878
:::info
7979

80-
Each layer of the `<ParallaxBanner>` is just a `useParallax` hook targeting a `<div>`. Which means anything you can use to configure [`useParallax`](/docs/usage/hooks/use-parallax) can be used as a property of a `layer`. See all [effects and configuration](https://parallax-controller.v1.damnthat.tv/docs/usage/props) accepted.
80+
Each layer of the `<ParallaxBanner>` is just a `useParallax` hook targeting a `<div>`. Which means anything you can use to configure [`useParallax`](/docs/usage/hooks/use-parallax) can be used as a property of a `layer`. See all [effects and configuration](/docs/usage/parallax-props) accepted.
8181

8282
:::

‎documentation/docs/examples/easing.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import { EasingDemo } from '/src/components/easing-demo';
66

77
# Easing Animation
88

9-
You can provide [easing presets](https://parallax-controller.v1.damnthat.tv/docs/usage/props#cubic-bezier-easing-function) or [cubic-bezier curve params](https://parallax-controller.v1.damnthat.tv/docs/usage/props#cubic-bezier-easing-function) to the `useParallax` hook or `<Parallax />` component.
9+
You can provide [easing presets](/docs/usage/parallax-props#cubic-bezier-easing-function) or [cubic-bezier curve params](/docs/usage/parallax-props#cubic-bezier-easing-function) to the `useParallax` hook or `<Parallax />` component.
1010

1111
## Example using a preset
1212

‎documentation/docs/examples/how-it-works.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,9 @@ All effects are applied based on the original element's progress. Progress begin
3535

3636
By design and by default, all elements progress relative to the view. However, there are optional ways to change how progress is calculated:
3737

38-
1. Manually setting [`startScroll` and `endScroll`](https://parallax-controller.v1.damnthat.tv/docs/usage/props#configuration-props) props allows complete control over when the progress starts and ends.
39-
2. Setting a [`rootMargin`](https://parallax-controller.v1.damnthat.tv/docs/usage/props#configuration-props) will add a invisible margin around the element that can be used to change when the element is in view and its progress.
40-
3. You can also set [`shouldAlwaysCompleteAnimation`](https://parallax-controller.v1.damnthat.tv/docs/usage/props#configuration-props) to true and if the element is positioned inside the view when scroll is at zero or ends in view at final scroll position, the initial and final positions are used to determine progress instead of the scroll view size.
38+
1. Manually setting [`startScroll` and `endScroll`](/docs/usage/parallax-props#configuration-props) props allows complete control over when the progress starts and ends.
39+
2. Setting a [`rootMargin`](/docs/usage/parallax-props#configuration-props) will add a invisible margin around the element that can be used to change when the element is in view and its progress.
40+
3. You can also set [`shouldAlwaysCompleteAnimation`](/docs/usage/parallax-props#configuration-props) to true and if the element is positioned inside the view when scroll is at zero or ends in view at final scroll position, the initial and final positions are used to determine progress instead of the scroll view size.
4141

4242
:::
4343

‎documentation/docs/usage/components/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Components",
3-
"position": 2
3+
"position": 3
44
}

‎documentation/docs/usage/hooks/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Hooks",
3-
"position": 1
3+
"position": 2
44
}

‎documentation/docs/usage/parallax-props.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Parallax Props
6+
7+
The following hooks and components accept the parallax prop configurations that setup scroll effects in the [Parallax Controller](https://parallax-controller.v1.damnthat.tv/docs/usage/props).
8+
9+
- [`useParallax()`](/docs/usage/hooks/use-parallax)
10+
- [`<Parallax>`](/docs/usage/components/parallax-component)
11+
- [`<ParallaxBanner>`](/docs/usage/components/parallax-banner-component)
12+
13+
Example with: **`useParallax()`**
14+
15+
```ts
16+
useParallax({
17+
speed: -10,
18+
...props,
19+
});
20+
```
21+
22+
Example with: **`<Parallax />`**
23+
24+
```tsx
25+
<Parallax speed={-10} {...props} />
26+
```
27+
28+
Example with **`<ParallaxBanner />`**
29+
30+
```tsx
31+
<Parallax
32+
layers={[
33+
{
34+
speed: -10,
35+
...props,
36+
},
37+
]}
38+
/>
39+
```
40+
41+
## Configuration Props
42+
43+
The following properties can be provided to configure the scroll animation:
44+
45+
| Name | Type | Default | Description |
46+
| ------------------------------------ | :--------------------: | :------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47+
| **speed** | `number` | | A value representing the elements scroll speed. If less than zero scroll will appear slower. If greater than zero scroll will appear faster. |
48+
| **easing** | `string` or `number[]` | | String representing an [easing preset](#easing-presets) or array of params to supply to a [cubic bezier easing function](#cubic-bezier-easing-function). |
49+
| **rootMargin** | `object` | | Margin to be applied as the bounds around an element. This will affect when an element is determined to be in the viewport. Example: `{ top: 100, right: 100, bottom: 100, left: 100 }` |
50+
| **disabled** | `boolean` | `false` | Disables parallax effects on individual elements when `true`. |
51+
| **shouldAlwaysCompleteAnimation** | `boolean` | `false` | Always start and end animations at the given effect values - if the element is positioned inside the view when scroll is at zero or ends in view at final scroll position, the initial and final positions are used to determine progress instead of the scroll view size. |
52+
| **shouldDisableScalingTranslations** | `boolean` | `false` | Enable scaling translations - translate effects that cause the element to appear in the view longer must be scaled up so that animation doesn't end early. |
53+
| **startScroll** | `number` | | Scroll top value to begin the animation. When provided along with `endScroll` relative scroll values will be ignored. |
54+
| **endScroll** | `number` | | Scroll top value to end the animation. When provided along with `startScroll` relative scroll values will be ignored. |
55+
56+
## CSS Effect Props
57+
58+
All props for creating CSS effects are defined by a **start** and **end** value represented by an `array`.
59+
60+
```ts
61+
useParallax({
62+
translateY: [-100, 100],
63+
});
64+
```
65+
66+
### How Effects Progress
67+
68+
The **start** of an effect begins when the top of the element enters the bottom of the view.
69+
70+
The **end** of an effect begins when the bottom of the element exits the top of the view.
71+
72+
:::info
73+
74+
See a demo of [how progress is determined](http://localhost:3000/docs/examples/how-it-works#progress-is-relative-to-the-view).
75+
76+
:::
77+
78+
### Available CSS Effects
79+
80+
These are all the supported CSS effects:
81+
82+
| Name | Type | Description |
83+
| -------------- | :----------------------: | ------------------------------------------------------------------------------------------------------------------------------------- |
84+
| **translateX** | `string[]` or `number[]` | Start and end translation on x-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements width. |
85+
| **translateX** | `string[]` or `number[]` | Start and end translation on x-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements width. |
86+
| **translateY** | `string[]` or `number[]` | Start and end translation on y-axis in `%` or `px`. If no unit is passed percent is assumed. Percent is based on the elements height. |
87+
| **rotate** | `string[]` or `number[]` | Start and end rotation on z-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed. |
88+
| **rotateX** | `string[]` or `number[]` | Start and end rotation on x-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed. |
89+
| **rotateY** | `string[]` or `number[]` | Start and end rotation on y-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed. |
90+
| **rotateZ** | `string[]` or `number[]` | Start and end rotation on z-axis in `deg`, `rad`, or `turn`. If no unit is passed `deg` is assumed. |
91+
| **scale** | `number[]` | Start and end scale on x-axis and y-axis. |
92+
| **scaleX** | `number[]` | Start and end scale on x-axis. |
93+
| **scaleY** | `number[]` | Start and end scale on y-axis. |
94+
| **scaleZ** | `number[]` | Start and end scale on z-axis. |
95+
| **opacity** | `number[]` | Start and end opacity value. |
96+
97+
## Callback Props
98+
99+
Example using `onChange` callback
100+
101+
```ts
102+
useParallax({
103+
onChange: (element) => console.log(element),
104+
});
105+
```
106+
107+
All available callbacks:
108+
109+
| Name | Type | Description |
110+
| -------------------- | :--------: | ------------------------------------------------------------------------------------------------------------ |
111+
| **onProgressChange** | `function` | Callback for when the progress of an element in the viewport changes. |
112+
| **onChange** | `function` | Callback for when the progress of an element in the viewport changes and includes the Element as a parameter |
113+
| **onEnter** | `function` | Callback for when an element enters the viewport. |
114+
| **onExit** | `function` | Callback for when an element exits the viewport. |
115+
116+
## Easing Presets
117+
118+
Example of setting easing:
119+
120+
```ts
121+
useParallax({
122+
easing: 'easeInCubic',
123+
});
124+
```
125+
126+
The following easing values are preset and can be used as easing
127+
128+
```
129+
ease
130+
easeIn
131+
easeOut
132+
easeInOut
133+
easeInQuad
134+
easeInCubic
135+
easeInQuart
136+
easeInQuint
137+
easeInSine
138+
easeInExpo
139+
easeInCirc
140+
easeOutQuad
141+
easeOutCubic
142+
easeOutQuart
143+
easeOutQuint
144+
easeOutSine
145+
easeOutExpo
146+
easeOutCirc
147+
easeInOutQuad
148+
easeInOutCubic
149+
easeInOutQuart
150+
easeInOutQuint
151+
easeInOutSine
152+
easeInOutExpo
153+
easeInOutCirc
154+
easeInBack
155+
easeOutBack
156+
easeInOutBack
157+
```
158+
159+
### Easing Individual Effects
160+
161+
You can provide various easing values to each effect by defining it as the third element in the array
162+
163+
```ts
164+
useParallax({
165+
translateY: [-100, 100, 'easeInOut'],
166+
scale: [0, 1, 'easeOutBack'],
167+
});
168+
```
169+
170+
### Cubic Bezier Easing Function
171+
172+
Just like with CSS `cubic-bezier(0.2,-0.67,1,-0.62);`, you can supply the 4 params to a custom bezier function.
173+
174+
```ts
175+
useParallax({
176+
translateY: [-100, 100],
177+
easing: [0.2, -0.6, 1, -0.6],
178+
});
179+
```

‎documentation/docusaurus.config.js‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,12 @@ const config = {
5252
position: 'left',
5353
label: 'Usage',
5454
},
55+
{
56+
type: 'doc',
57+
docId: 'usage/parallax-props',
58+
position: 'left',
59+
label: 'Props',
60+
},
5561
{
5662
type: 'doc',
5763
docId: 'usage/hooks/hooks',
@@ -82,11 +88,32 @@ const config = {
8288
style: 'dark',
8389
links: [
8490
{
85-
title: 'Docs',
91+
title: 'Introduction',
92+
items: [
93+
{
94+
to: '/docs/usage/usage',
95+
label: 'Usage',
96+
},
97+
{
98+
to: '/docs/examples/how-it-works',
99+
label: 'Examples',
100+
},
101+
],
102+
},
103+
{
104+
title: 'Reference',
86105
items: [
87106
{
88-
label: 'Introduction',
89-
to: '/docs/intro',
107+
to: '/docs/usage/parallax-props',
108+
label: 'Props',
109+
},
110+
{
111+
to: '/docs/usage/hooks/hooks',
112+
label: 'Hooks',
113+
},
114+
{
115+
to: '/docs/usage/components/components',
116+
label: 'Components',
90117
},
91118
],
92119
},

0 commit comments

Comments
 (0)