# `@castlenine/svelte-aoe`
[![npm.badge]][npm] [![download.badge]][download] [![contribution.badge]][contribution]
A Svelte component for animating elements, with no dependencies.
`@castlenine/svelte-aoe` uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to detect when an element enters the viewport.
When the element enters the viewport, `@castlenine/svelte-aoe` applies a class that triggers a CSS animation.
## 🚀 [Demo](https://castlenine-svelte-aoe.vercel.app/)
## Installation
Use your package manager to install:
```shell
npm i @castlenine/svelte-aoe
```
## Setup
1. Import and add the component **once** in your root layout:
File: `src/routes/+layout.svelte`
```svelte
```
2. Add a `data-aoe` attribute to any element you want to animate:
```svelte
```
Elements are automatically detected, including those added dynamically by page navigation.
## Animations
### Normal speed
- `up`
- `right`
- `left`
- `down`
- `fade`
- `fade-up`
- `fade-right`
- `fade-left`
- `fade-down`
### Fast speed
- `up-fast`
- `right-fast`
- `left-fast`
- `down-fast`
- `fade-fast`
- `fade-up-fast`
- `fade-right-fast`
- `fade-left-fast`
- `fade-down-fast`
### Slow speed
- `up-slow`
- `right-slow`
- `left-slow`
- `down-slow`
- `fade-slow`
- `fade-up-slow`
- `fade-right-slow`
- `fade-left-slow`
- `fade-down-slow`
### Normal speed partial fade
Starts with `0.25` opacity
- `partial-fade`
- `partial-fade-up`
- `partial-fade-right`
- `partial-fade-left`
- `partial-fade-down`
### Fast speed partial fade
Starts with `0.25` opacity
- `partial-fade-fast`
- `partial-fade-up-fast`
- `partial-fade-right-fast`
- `partial-fade-left-fast`
- `partial-fade-down-fast`
### Slow speed partial fade
Starts with `0.25` opacity
- `partial-fade-slow`
- `partial-fade-up-slow`
- `partial-fade-right-slow`
- `partial-fade-left-slow`
- `partial-fade-down-slow`
You can add your own animations by following the same pattern in your CSS.
```css
[data-aoe='your-animation'] {
transform: translateX(-45px);
transition:
transform 600ms,
opacity 900ms;
&.aoe {
transform: translateX(0);
transition-delay: 0s;
}
}
```
## Properties
| Property name | Type | Default value |
| ------------- | --------------------------------------------- | ------------- |
| `root` | `Document`, `Element`, `null`, `undefined` | `null` |
| `rootMargin` | `string` in pixels (`px`) or percentage (`%`) | `0px` |
| `threshold` | `number`, `number[]` between `0` and `1.0` | `0.3` |
`root` is the element used as the viewport for checking the visibility of the target. It must be an ancestor of the target. If not specified or if set to `null`, it defaults to the browser viewport.
`rootMargin` is the margin around the root. It can have values similar to the CSS margin property, e.g., `"10px 20px 30px 40px"` (top, right, bottom, left). The values can be percentages. The default is `'0px'` (no margin).
`threshold` is either a single number or an array of numbers, indicating at what percentage of the target's visibility the observer's callback should be executed. A value of `0.0` or `0` indicates that even a single pixel of the target is visible. A value of `1.0` or `1` requires the target to be completely visible. The default is `0.3` (30%).
## Scoped Overrides
Set defaults for all `data-aoe` elements within a page or section using `data-aoe-scope` on a container element, or the `` convenience component. Elements inside a scope inherit its values unless they have their own per-element `data-aoe-*` overrides.
### Using the `data-aoe-scope` attribute
```svelte
```
### Using the `` component
```svelte
```
| Property name | Type | Default value |
| ------------- | --------------------------------------------- | ------------- |
| `root` | CSS selector `string` | `undefined` |
| `rootMargin` | `string` in pixels (`px`) or percentage (`%`) | `undefined` |
| `threshold` | `number` between `0` and `1.0` | `undefined` |
Scopes can be nested. The innermost scope takes precedence.
## Per-Element Overrides
Individual elements can override scope or global properties using `data-aoe-*` attributes. If an attribute is not set, the value from the nearest `data-aoe-scope` ancestor is used, then ``, and then the package default.
| Attribute | Type | Overrides |
| ---------------------- | --------------------------------------------- | ------------ |
| `data-aoe-threshold` | `number` between `0` and `1.0` | `threshold` |
| `data-aoe-root` | CSS selector `string` | `root` |
| `data-aoe-root-margin` | `string` in pixels (`px`) or percentage (`%`) | `rootMargin` |
### Examples
```svelte
```
---
Inspired by [Animate on Scroll](https://michalsnik.github.io/aos/) and forked from [lliamscholtz/svelte-aoe](https://github.com/lliamscholtz/svelte-aoe)
[npm]: https://www.npmjs.com/package/@castlenine/svelte-aoe
[npm.badge]: https://img.shields.io/npm/v/@castlenine/svelte-aoe
[download]: https://www.npmjs.com/package/@castlenine/svelte-aoe
[download.badge]: https://img.shields.io/npm/d18m/@castlenine/svelte-aoe
[contribution]: https://github.com/Castlenine/svelte-aoe
[contribution.badge]: https://img.shields.io/badge/contributions-welcome-green