react-awesome-reveal 4.0.0-beta.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +223 -0
- package/dist/main.js +548 -759
- package/dist/main.js.map +1 -1
- package/dist/module.js +564 -750
- package/dist/module.js.map +1 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +31 -16
package/README.md
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# React Awesome Reveal
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/react-awesome-reveal/v/latest)
|
|
4
|
+
[](https://github.com/morellodev/react-awesome-reveal/commits/master)
|
|
5
|
+
[](https://www.npmjs.com/package/react-awesome-reveal/v/latest)
|
|
6
|
+
[](https://bundlephobia.com/result?p=react-awesome-reveal@latest)
|
|
7
|
+
[](https://www.npmjs.com/package/react-awesome-reveal/v/latest)
|
|
8
|
+
[](https://openbase.io/js/react-awesome-reveal?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge)
|
|
9
|
+
|
|
10
|
+
[React Awesome Reveal](https://github.com/morellodev/react-awesome-reveal) is a library for React apps written in TypeScript that adds reveal animations using the Intersection Observer API to detect when the elements appear in the viewport. Animations are internally provided by [Emotion](https://emotion.sh) and implemented as CSS Animations to benefit from hardware acceleration.
|
|
11
|
+
|
|
12
|
+
## Table Of Contents
|
|
13
|
+
|
|
14
|
+
- [Features](#features)
|
|
15
|
+
- [Demo](#demo)
|
|
16
|
+
- [Installation](#installation)
|
|
17
|
+
- [Quick Start](#quick-start)
|
|
18
|
+
- [Supported Effects](#supported-effects)
|
|
19
|
+
- [Attention Seekers](#attention-seekers)
|
|
20
|
+
- [Props](#props)
|
|
21
|
+
- [Example](#example)
|
|
22
|
+
- [Chaining Multiple Animations](#chaining-multiple-animations)
|
|
23
|
+
- [Custom Animations](#custom-animations)
|
|
24
|
+
- [Other Props](#other-props)
|
|
25
|
+
- [Intersection Observer](#intersection-observer)
|
|
26
|
+
- [Polyfill](#polyfill)
|
|
27
|
+
- [Past Releases](#past-releases)
|
|
28
|
+
- [License](#license)
|
|
29
|
+
|
|
30
|
+
## Features
|
|
31
|
+
|
|
32
|
+
- 🎁 **Modern stack** – It is built for modern React and supports React 18
|
|
33
|
+
- 🏷 **TypeScript support** – It is written in TypeScript to improve the DX
|
|
34
|
+
- 🍃 **Lightweight** – Very little footprint on your project
|
|
35
|
+
- ⚙️ **Uses native APIs** – Intersection Observer and CSS Animations are now supported by all browsers
|
|
36
|
+
- 🚀 **Fast** – Buttery smooth experience thanks to the use of native asynchronous APIs and hardware acceleration
|
|
37
|
+
- 💅 **Fully customizable** – Define custom animations and let the library render them
|
|
38
|
+
- 💻 **SSR support** – Server Side Rendering works out-of-the-box
|
|
39
|
+
- 🌳 **Tree-shakeable** – Only the parts you use will be included in your final bundle
|
|
40
|
+
|
|
41
|
+
## Installation
|
|
42
|
+
|
|
43
|
+
To add this package as a dependency to your app, simply run
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npm install react-awesome-reveal @emotion/react --save
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
or, if you are using Yarn (as I strongly suggest):
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
yarn add react-awesome-reveal @emotion/react
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
Import effects from [React Awesome Reveal](https://www.npmjs.com/package/react-awesome-reveal) to your React component, for example the `Fade` effect:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { Fade } from "react-awesome-reveal";
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Then simply wrap the components you want to animate:
|
|
64
|
+
|
|
65
|
+
```jsx
|
|
66
|
+
<Fade>
|
|
67
|
+
<p>I will gently appear as I enter the viewport</p>
|
|
68
|
+
</Fade>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Supported Effects
|
|
72
|
+
|
|
73
|
+
The effects currently supported are `Bounce`, `Fade`, `Flip`, `Hinge`, `JackInTheBox`, `Roll`, `Rotate`, `Slide` and `Zoom`. Refer to the [Animate.css](https://animate.style) documentation for the details.
|
|
74
|
+
|
|
75
|
+
### Attention Seekers
|
|
76
|
+
|
|
77
|
+
Since version 3, attention seeker animations are wrapped by the `AttentionSeeker` component, which accepts a prop called `effect` that specifies the animation to render (defaults to `"bounce”`). The supported effects are: `”bounce"`, `"flash"`, `"headShake”`, `"heartBeat"`, `"jello”`, `"pulse"`, `"rubberBand"`, `“shake”`, `“shakeX"`, `"shakeY”`, `"swing”`, `"tada"` and `“wobble”`.
|
|
78
|
+
|
|
79
|
+
Again, refer to the [Animate.css](https://animate.style) documentation for the details.
|
|
80
|
+
|
|
81
|
+
### Props
|
|
82
|
+
|
|
83
|
+
You can pass the following props to the animation components to customize the behavior:
|
|
84
|
+
|
|
85
|
+
| Prop | Description | Values | Default |
|
|
86
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
87
|
+
| `cascade` | If set, each child of a reveal animation automatically get assigned a delay that takes into account their predecessor (child `i` enters the viewport after `i * delay * damping` milliseconds) – useful for animating list items. | `true` or `false` | `false` |
|
|
88
|
+
| `damping` | Factor that affects the delay that each animated component in a cascade animation will be assigned. If `damping = 1` then the delay will be equal to the animation duration; if `damping < 1` then the delay will be lower than the animation duration; if `damping > 1` then the delay will be greater than the animation duration. | `number` | `0.5` (meaning that the delay will be half of the animation duration) |
|
|
89
|
+
| `direction` | Origin of the animation (where applicable). | Usually `"down"`, `"left"`, `"right"` or `"up"`, with some exceptions documented in the code | `undefined` |
|
|
90
|
+
| `delay` | Time to wait before the animation starts (in milliseconds). | `number` | `0` |
|
|
91
|
+
| `duration` | The animation duration (milliseconds). | `number` | `1000` |
|
|
92
|
+
| `fraction` | How much an element should be in viewport before the animation is triggered. | `number` between `0` and `1` | `0` |
|
|
93
|
+
| `triggerOnce` | Specifies if the animation should run only once or everytime an element enters/exits/re-enters the viewport. | `true` or `false` | `false` |
|
|
94
|
+
| `className` | The class names to add to the container element. | `string` | `undefined` |
|
|
95
|
+
| `style` | The inline styles to add to the container element. | `React.CSSProperties` | `undefined` |
|
|
96
|
+
| `childClassName` | The class names to add to the child element. | `string` | `undefined` |
|
|
97
|
+
| `childStyle` | The inline styles to add to the child element. | `React.CSSProperties` | `undefined` |
|
|
98
|
+
| `onVisibilityChange` | Callback executed when the element enters or leaves the viewport. If more than one element is being animated, this function is called on each element. | `(inView: boolean, entry: IntersectionObserverEntry) => void` | `undefined` |
|
|
99
|
+
|
|
100
|
+
### Example
|
|
101
|
+
|
|
102
|
+
To trigger the animation only the first time an element enters the viewport:
|
|
103
|
+
|
|
104
|
+
```jsx
|
|
105
|
+
<Slide triggerOnce>
|
|
106
|
+
<p>I will animate only the first time you see me</p>
|
|
107
|
+
</Slide>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Chaining Multiple Animations
|
|
111
|
+
|
|
112
|
+
To chain together multiple animations, set the `cascade` prop to `true`:
|
|
113
|
+
|
|
114
|
+
```jsx
|
|
115
|
+
<Fade cascade>
|
|
116
|
+
<p>I enter first...</p>
|
|
117
|
+
<p>...then comes my turn...</p>
|
|
118
|
+
<p>...and finally you see me!</p>
|
|
119
|
+
</Fade>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
This is _almost_ equivalent to
|
|
123
|
+
|
|
124
|
+
```jsx
|
|
125
|
+
<Fade>
|
|
126
|
+
<p>I enter first...</p>
|
|
127
|
+
</Fade>
|
|
128
|
+
<Fade delay={1000}>
|
|
129
|
+
<p>...then comes my turn...</p>
|
|
130
|
+
</Fade>
|
|
131
|
+
<Fade delay={2000}>
|
|
132
|
+
<p>...and finally you see me!</p>
|
|
133
|
+
</Fade>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
with the exception that, since each `Fade` component creates an isolated visibility context, in the second snippet every `p` will be shown only if they are inside the viewport (after the specified delay).
|
|
137
|
+
|
|
138
|
+
## Custom Animations
|
|
139
|
+
|
|
140
|
+
Starting from version 3.2.0, you can define custom animations! Simply import the `Reveal` component (which is the default export of the library – give it the name you want) and pass it a `keyframes` prop:
|
|
141
|
+
|
|
142
|
+
```jsx
|
|
143
|
+
import React from "react";
|
|
144
|
+
import Reveal from "react-awesome-reveal";
|
|
145
|
+
import { keyframes } from "@emotion/react";
|
|
146
|
+
|
|
147
|
+
const customAnimation = keyframes`
|
|
148
|
+
from {
|
|
149
|
+
opacity: 0;
|
|
150
|
+
transform: translate3d(-200px, -100px, 0);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
to {
|
|
154
|
+
opacity: 1;
|
|
155
|
+
transform: translate3d(0, 0, 0);
|
|
156
|
+
}
|
|
157
|
+
`;
|
|
158
|
+
|
|
159
|
+
function MyAnimatedComponent({ children }) {
|
|
160
|
+
return (
|
|
161
|
+
<Reveal keyframes={customAnimation}>
|
|
162
|
+
{children}
|
|
163
|
+
</Reveal>;
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
If no `keyframes` prop is passed, the default rendered animation is a fading entrance from the left (equivalent to `<Fade direction="left">...</Fade>`).
|
|
169
|
+
|
|
170
|
+
### Other Props
|
|
171
|
+
|
|
172
|
+
You can also pass these props to `Reveal`:
|
|
173
|
+
|
|
174
|
+
- `cascade`
|
|
175
|
+
- `damping`
|
|
176
|
+
- `delay`
|
|
177
|
+
- `duration`
|
|
178
|
+
- `fraction`
|
|
179
|
+
- `triggerOnce`
|
|
180
|
+
- `className` and `childClassName`
|
|
181
|
+
- `style` and `childStyle`
|
|
182
|
+
- `onVisibilityChange`
|
|
183
|
+
|
|
184
|
+
## Intersection Observer
|
|
185
|
+
|
|
186
|
+
[Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) is the API used to determine if an element is inside the viewport or not. [Browser support](http://caniuse.com/#feat=intersectionobserver) is really good – with [Safari adding support in 12.1](https://webkit.org/blog/8718/new-webkit-features-in-safari-12-1), all major browsers now support Intersection Observers natively.
|
|
187
|
+
|
|
188
|
+
If you need to support old browsers, add the polyfill for the Intersection Observer API.
|
|
189
|
+
|
|
190
|
+
### Polyfill
|
|
191
|
+
|
|
192
|
+
You can add the [polyfill](https://www.npmjs.com/package/intersection-observer) directly or use a service like [polyfill.io](https://polyfill.io/v2/docs) to add it when needed.
|
|
193
|
+
|
|
194
|
+
```sh
|
|
195
|
+
yarn add intersection-observer
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Then import it in your app:
|
|
199
|
+
|
|
200
|
+
```javascript
|
|
201
|
+
import "intersection-observer";
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
If you are using Webpack (or similar) you could use [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports) to load the polyfill only if needed. A basic implementation could look something like this:
|
|
205
|
+
|
|
206
|
+
```javascript
|
|
207
|
+
/**
|
|
208
|
+
* Do feature detection, to figure out which polyfills needs to be imported.
|
|
209
|
+
**/
|
|
210
|
+
async function loadPolyfills() {
|
|
211
|
+
if (typeof window.IntersectionObserver === "undefined") {
|
|
212
|
+
await import("intersection-observer");
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Past Releases
|
|
218
|
+
|
|
219
|
+
To see the documentation for previous versions, navigate through past tags in the GitHub's project repository and read the README for that specific version.
|
|
220
|
+
|
|
221
|
+
## License
|
|
222
|
+
|
|
223
|
+
Project source code is licensed under the MIT license. You are free to fork this repository, edit the code, share and use it both for non-commercial and commercial purposes.
|