You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+26-26
Original file line number
Diff line number
Diff line change
@@ -8,14 +8,14 @@
8
8
9
9
svelte-reveal is a library created with the purpose of helping [Svelte](https://svelte.dev/) users add reveal on scroll transitions to their web applications. This library leverages the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) in order to know when to trigger the animations.
10
10
11
-
## ✨ Features
11
+
## Features
12
12
13
13
- Zero config Svelte action
14
14
- Highly customizable transitions
15
15
- Integrates a performant intersection observer
16
16
- TypeScript ready
17
17
18
-
## 📖 Table of Content
18
+
## Table of Content
19
19
20
20
1.[Usage](#usage)
21
21
2.[Demo](#demo)
@@ -31,7 +31,7 @@ svelte-reveal is a library created with the purpose of helping [Svelte](https://
31
31
12.[Changelog](#changelog)
32
32
13.[License](#license)
33
33
34
-
## 🔨 Usage
34
+
## Usage
35
35
36
36
1. Install the library. You can use either [npm](https://www.npmjs.com/):
37
37
@@ -83,7 +83,7 @@ svelte-reveal is a library created with the purpose of helping [Svelte](https://
83
83
84
84
4. Using [SvelteKit](https://kit.svelte.dev/)? Please read [section "SvelteKit"](#sveltekit)
85
85
86
-
### 🐳 Docker
86
+
### Docker
87
87
88
88
A Docker image is also available on [DockerHub](https://hub.docker.com/):
You can also use the provided Dockerfile in the repository as a development environment. You can read more [here](https://code.visualstudio.com/docs/remote/containers).
95
95
96
-
## 🕺🏻 Demo
96
+
## Demo
97
97
98
98
In this [Svelte REPL](https://svelte.dev/repl/1cf37b0947ac46b8ae9cc791abda7159?version=3.44.1) I created you can see svelte-reveal in action.
99
99
100
-
## 🤔 Why svelte-reveal
100
+
## Why svelte-reveal
101
101
102
102
If you happened to scout the internet for other similar libraries, you would have noticed that other authors have decided to create their own library using Svelte [slots](https://svelte.dev/docs#slot) (similar to [React children](https://reactjs.org/docs/composition-vs-inheritance.html)). There is nothing wrong with that approach, but in my opinion it goes a bit against one of Svelte's core purposes: writing less code. Having to wrap every to-be-transitioned component adds 2 extra lines of code each time, making your files unnecessarily bloated for such a simple add-on.
103
103
104
104
You might have also noticed people adding event listeners to the window object, but in terms of performance that [doesn't scale very well](https://itnext.io/1v1-scroll-listener-vs-intersection-observers-469a26ab9eb6).
105
105
106
106
Instead, I decided to use Svelte [actions](https://svelte.dev/docs#use_action), which are functions you can attach to a DOM element and that allow you to get access to that element and its lifecycle. They take up considerably less space and so far I haven't encountered any obstacle or performance drawback. Morever, this library is backed by the Intersection Observer API, which is great for performance.
107
107
108
-
## ⚠️ SvelteKit
108
+
## SvelteKit
109
109
110
110
The way svelte-reveal transitions the elements does not work well with [SSR](https://kit.svelte.dev/docs/appendix#ssr), which is enabled by default on SvelteKit. One way to get around this issue is to wrap your top-most element or component inside an if-block that is evaluated to `true` only when its context has been updated, as in the following example.
111
111
@@ -123,11 +123,11 @@ In case of problems, please create a new issue and submit a bug report.
123
123
</script>
124
124
125
125
{#if show}
126
-
<your-element-or-component />
126
+
<your-element-or-component />
127
127
{/if}
128
128
```
129
129
130
-
## ⛩ Options
130
+
## Options
131
131
132
132
Depending on the use case, you can either use this library as-is (which applies some [default styles](https://github.com/DaveKeehl/svelte-reveal/blob/main/src/internal/config.ts#L6-L37)), or customize it to your liking. If you choose to do so, you can pass an object to this action containing additional options.
133
133
@@ -159,20 +159,20 @@ Keep in mind that these options are applied to the single DOM element you add sv
159
159
| blur |`number`|`16`| The starting blur value in pixels (_px_) of the `"blur"` transition. |
160
160
| scale |`number`|`0`| The starting scale value in percentage (_%_) of the `"scale"` transition. |
161
161
162
-
### 🪄 Transitions
162
+
### Transitions
163
163
164
164
The following are all the transitions available by svelte-reveal. The names listed in the table match the ones you can write in your source code. All transitions have the fade transition backed in.
| fade | The element fades in gracefully.<br />In practice: `opacity: 0 -> 1`|
169
-
| fly | The element fades in and performs a translation on the y-axis (vertical).<br />In practice: `opacity: 0 -> 1` and `transform: translateY(-20px -> 0px) `|
| fade | The element fades in gracefully.<br />In practice: `opacity: 0 -> 1`|
169
+
| fly | The element fades in and performs a translation on the y-axis (vertical).<br />In practice: `opacity: 0 -> 1` and `transform: translateY(-20px -> 0px) `|
170
170
| slide | The element fades in and performs a translation on the x-axis (horizontal).<br />In practice: `opacity: 0 -> 1` and `transform: translateX(-20px -> 0px)`|
171
-
| blur | The element fades in and becomes unblurred.<br />In practice: `opacity: 0 -> 1` and `filter: blur(8px -> 0px)`|
172
-
| scale | The element fades in and gets to the original size.<br />In practice: `opacity: 0 -> 1` and `transform: scale(0 -> 1)`|
173
-
| spin | The element fades in and gets to the original rotation degree.<br />In practice: `opacity: 0 -> 1` and `transform: rotate(-360 -> 0)`|
171
+
| blur | The element fades in and becomes unblurred.<br />In practice: `opacity: 0 -> 1` and `filter: blur(8px -> 0px)`|
172
+
| scale | The element fades in and gets to the original size.<br />In practice: `opacity: 0 -> 1` and `transform: scale(0 -> 1)`<br /><br />⚠️ In order to use this transition it is required to use the `width` CSS property on the element to reveal. If you are not already using this property for other things, you can set it to `width: fit-content` .|
173
+
| spin | The element fades in and gets to the original rotation degree.<br />In practice: `opacity: 0 -> 1` and `transform: rotate(-360 -> 0)`<br /><br />⚠️ In order to use this transition it is required to use the `width` CSS property on the element to reveal. If you are not already using this property for other things, you can use set it to `width: fit-content` .|
174
174
175
-
### 🤙🏻 Callbacks
175
+
### Callbacks
176
176
177
177
Among the available options you can set, there are also some callback functions you can leverage to inject some code during specific moments of the lifecycle of the nodes attached to this action.
178
178
@@ -186,7 +186,7 @@ Among the available options you can set, there are also some callback functions
186
186
| onUpdate |`(node: HTMLElement)`|`void`| Function that gets fired when the action options are updated. |
187
187
| onDestroy |`(node: HTMLElement)`|`void`| Function that gets fired when the node is unmounted from the DOM. |
188
188
189
-
## 📄 Global config
189
+
## Global config
190
190
191
191
This library is globally configured as follows right of out the box:
192
192
@@ -212,7 +212,7 @@ This library is globally configured as follows right of out the box:
212
212
|| rootMargin ||`string`|`"0px 0px 0px 0px"`| The Intersection Observer API rootMargin property. |
213
213
|| threshold ||`number`|`0.6`| The Intersection Observer API threshold property. |
214
214
215
-
## ⚡️ API
215
+
## API
216
216
217
217
> 💡 All API functions return the global config object with the updated properties.
|`(options: IOptions)`|`IOptions`| You can use this function to override the global default options of the reveal effect. It can be useful when you want a specific option for many elements, so that you don't have to change it for every element individually. |
355
355
356
-
## 👀 Suggestions
356
+
## Suggestions
357
357
358
358
In order to take full advantage of this library, I suggest you to create some environment variables to keep track of the environment you are currently in (e.g. development, staging, production) and to leverage NPM scripts to update those variables. [This article](https://www.twilio.com/blog/working-with-environment-variables-in-node-js-html) explains well this concept.
359
359
360
360
That way you can for example set the config `dev` property to `false` when in production and avoid exposing console logs to the end users.
361
361
362
362
If you use [SvelteKit](https://kit.svelte.dev/), this feature is available right out of the box with the [$app/env](https://kit.svelte.dev/docs#modules-$app-env) module.
363
363
364
-
## 🤕 Troubleshooting
364
+
## Troubleshooting
365
365
366
366
Feel free to [open a new issue](https://github.com/DaveKeehl/svelte-reveal/issues/new/choose) in case of any problems.
367
367
368
-
## ☕️ Funding
368
+
## Funding
369
369
370
370
[Want to buy me a coffee?](https://ko-fi.com/davekeehl)
371
371
372
-
## 📚 Versioning
372
+
## Versioning
373
373
374
374
This project uses [Semantic Versioning](https://semver.org/) to keep track of its version number.
0 commit comments