svelte-reveal v1.1.0

Svelte Reveal

Svelte Reveal is a library created with the purpose of helping Svelte users add reveal on scroll animations to their web applications in the easiest way possible. This library leverages the Intersection Observer API in order to know when to trigger the animations.

Features

• ⚡️ Near zero config
• 👀 Intersection Observer
• 🧩 Customizable transitions
• 🔌 Extensive API
• 📚 Exhaustive documentation
• 🔥 100% TypeScript

Table of Contents

1. Demo
2. Usage
3. Why Svelte Reveal
4. SvelteKit
5. Options
6. Global config
7. API
8. Suggestions
9. Troubleshooting
10. Funding
11. Versioning
12. Changelog
13. License

Demo

You can see Svelte Reveal in action in this StackBlitz project.

Usage

1. Install the library:

   # npm
   npm install -D svelte-reveal
   
   # yarn
   yarn add -D svelte-reveal
   
   # pnpm
   pnpm add -D svelte-reveal
   
   # bun
   bun add -D svelte-reveal

2. Import the library in your Svelte component:

   <script>
     import { reveal } from 'svelte-reveal';
   </script>

3. Add the imported reveal action to the DOM element you want to transition:

   <h1 use:reveal>Hello world</h1>
   <p use:reveal={{ transition: "slide" }}>A paragraph</p>

   If you want to use the action on a Svelte component, you need to pass the reveal options via props:

   // App.svelte
   
   <script>
     import Heading from './Heading.svelte';
   </script>
   
   <Heading useReveal={{ transition: "slide" }}>Hello world</Heading>

   // Heading.svelte
   
   <script lang="ts">
     import { reveal, type RevealOptions } from 'svelte-reveal';
     export let useReveal: RevealOptions;
   </script>
   
   <h1 use:reveal={ useReveal }>
     <slot />
   </h1>

   Using SvelteKit? Please refer to the "SvelteKit" section.

Why Svelte Reveal

If you happened to scout the internet for other similar libraries, you might have noticed that other authors have decided to create their own library using Svelte slots (similar to React children). There is nothing wrong with that approach, but in my opinion it goes a bit against one of Svelte's core purpose: writing more concise code. Having to wrap every to-be-transitioned component adds at least 2 extra lines of code each time, making your files unnecessarily bloated for such a simple add-on.

You might have also noticed people adding event listeners to the window object in order to transition elements, but in terms of performance it doesn't scale very well.

Instead, I decided to use Svelte actions, which are functions you can attach to a DOM element and that allow you to get access to that particular element and hook into its lifecycle. They take up considerably fewer lines of code, and so far I haven't encountered any big obstacle or performance drawback. Morever, this library is backed by the Intersection Observer API, which is great for performance.

SvelteKit

⚠️ This is an active area of research. Please submit a bug report in case of issues.

📅 Last update: April 2024

Since Svelte actions were conceived to operate in a client-side environment, they don't always work 100% in SvelteKit and SSR (server-side rendering) out of the box. Svelte Reveal is no exception, as it needs DOM access, and in order not to incur in weird animation behaviors some small setup is required by the end-users. Out of the following two methods, pick the one that most suit your project requirements.

Without SSR

If your page doesn't need to be server-side rendered then the fix is very trivial. Turn off ssr in your +page.ts file as follows.

// +page.ts
export const ssr = false;

With SSR

If your page does need to leverage server-side rendering, the setup remains easy but it requires a few more steps.

1. Import the bundled stylesheet in your page or layout

   // +layout.svelte
   
   <script lang="ts">
     import "svelte-reveal/styles.css";
     ...
   </script>
   
   ...

2. Add the sr__hide css class to every element targeted by Svelte Reveal with use:reveal. This will prevent the elements to flicker as soon as the page is hydrated and the DOM is accessible to the library.

   // +page.svelte
   
   <script lang="ts">
     import { reveal } from 'svelte-reveal';
   </script>
   
   <h1 use:reveal class="sr__hide">Hello world</h1>

Options

Depending on the use case, you can either use this library as-is (which applies some default options), or customize it to your liking. If you choose to do so, you can pass an object to this action containing your own options to be applied.

Keep in mind that these options are applied to the single DOM element you add Svelte Reveal to. For global and more in-depth settings, refer to the API section.

Presets

⚠️ All presets have the "fade" preset backed in

Presets are sets of options with predefined values, packaged under a name to achieve a certain transition effect. The following table shows the presets that come bundled with Svelte Reveal and which options they map to.

Callbacks

The following table shows all the callback functions we provide to you.

Global config

The following table shows how this library is globally configured right of out the box.

API

⚠️ If you want to customise the behavior of a single DOM node, you are supposed to use options.

Svelte Reveal also exposes several functions you can call to change the default options and global configuration of this library. Since these functions operate on a global level across all components using Svelte Reveal, you are supposed to only call them from a single file, otherwise you'll keep overriding the default options and global config from multiple points.

Suggestions

If you need to considerably customize the behavior of this library, I suggest creating a dedicated file and to import it from the top-most component in the components tree of your project. Within that file you can then call the API functions to set global settings or shared transition properties.

// reveal.config.ts

import { setDefaultOptions } from 'svelte-reveal';

setDefaultOptions({
  blur: 20,
  x: -50,
  duration: 3000
});

// App.svelte

<script>
  import 'reveal.config';
</script>

<div>{ your markup goes here }</div>

Troubleshooting

Feel free to open a new issue in case of any problems.

Funding

Want to buy me a coffee?

Versioning

This project uses Semantic Versioning to keep track of its version number.

Changelog

CHANGELOG

License

MIT