⚠️  Svelte Reveal is currently in beta. Do you want to contribute? Do you want to report a bug?

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.

• Zero config Svelte action
• Highly customizable transitions
• Utilizes the Intersection Observer API
• TypeScript ready

1. Usage
2. Demo
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

1. Install the library. You can use either npm:

   npm install -D svelte-reveal

   yarn:

   yarn add -D svelte-reveal

   or pnpm:

   pnpm add -D svelte-reveal

2. Import the library within your Svelte component:

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

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

   <h1 use:reveal>Your title</h1>
   <p use:reveal={{ transition: "fade" }}>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: "fade" }}>Hello world</Heading>
   
   // Heading.svelte
   <script lang="ts">
     import { reveal } from 'svelte-reveal';
     import type { RevealOptions } from 'svelte-reveal';
     export let useReveal: RevealOptions;
   </script>
   
   <h1 use:reveal={ useReveal }>
     <slot />
   </h1>

   Using SvelteKit? Please read section "SvelteKit"

A Docker image is also available on DockerHub:

docker pull davekeehl/svelte-reveal:latest

You can also use the provided Dockerfile in the repository as a development environment. You can read more here.

In this Svelte REPL I created you can see Svelte Reveal in action.

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 (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 obstacle or performance drawback. Morever, this library is backed by the Intersection Observer API, which is great for performance.

The way Svelte Reveal transitions the elements does not work well with SSR, which is enabled by default on SvelteKit. One way to get around this issue, is to wrap your top-most element or component in your app inside an if-block that is evaluated to true only when its context has been updated, as in the following example.

<script>
  import { afterUpdate } from 'svelte';

  let show = false;

  afterUpdate(() => {
    show = true;
  });
</script>

{#if show}
  <your-element-or-component />
{/if}

Please create a new issue and submit a bug report in case of problems.

Depending on the use case, you can either use this library as-is (which applies some default styles), 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.

The following are all the transitions available. The names listed in the table below match the ones available in your source code. All transitions have the fade transition backed in.

Among the available options, there are also some callback functions you can leverage to inject code during specific moments of the lifecycle of the DOM node attached to this action.

This library is globally configured as follows right of out the box:

⚠️ If you want to customise the behavior of a single DOM node, you are supposed to use the 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.

If you need/want to considerably customize the behavior of this library, I suggest creating a dedicated file (e.g. reveal.config.js) 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.

// App.svelte

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

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

Since this library has been built using TypeScript, there are many custom types used throughout the entire codebase. The following types are the main ones used by the API:

type Device = 'mobile' | 'tablet' | 'laptop' | 'desktop';

interface IDevice {
  enabled: boolean;
  breakpoint: number;
}

interface Responsive {
  [P in Device]: IDevice;
}

interface IObserverOptions {
  root: IntersectionObserver['root'];
  rootMargin: IntersectionObserver['rootMargin'];
  threshold: number;
}

interface RevealConfig {
  dev: boolean;
  once: boolean;
  responsive: Responsive;
}

interface RevealOptions {
  disable?: boolean;
  debug?: boolean;
  ref?: string;
  highlightLogs?: boolean;
  highlightColor?: string;
  root?: IntersectionObserver['root'];
  rootMargin?: IntersectionObserver['rootMargin'];
  threshold?: number;
  ...
  onUpdate?: (node: HTMLElement) => void;
  onDestroy?: (node: HTMLElement) => void;
}

It's not by any means required, but in order to take full advantage of this library, I suggest creating some environment variables to keep track of the environment the application is currently in (e.g. development, production) and to leverage NPM scripts to update those variables. This article explains well this concept.

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.

If you use SvelteKit you can import the dev variable from the $app/environment module. If you are using Vite, you can use the import.meta.env.DEV available from its env variables and modes.

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

Want to buy me a coffee?

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

CHANGELOG

MIT