https://github.com/penguin-32/asa
Angular Scroll Animations - Angular library for automatic element animations.
https://github.com/penguin-32/asa
angular animation library npm-package package scroll
Last synced: about 1 month ago
JSON representation
Angular Scroll Animations - Angular library for automatic element animations.
- Host: GitHub
- URL: https://github.com/penguin-32/asa
- Owner: Penguin-32
- Created: 2023-01-26T08:32:37.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-27T15:21:34.000Z (about 3 years ago)
- Last Synced: 2025-03-11T16:42:17.931Z (over 1 year ago)
- Topics: angular, animation, library, npm-package, package, scroll
- Language: TypeScript
- Homepage:
- Size: 1.14 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# ASA - Angular Scroll Animations
Versatile library to easily animate elements as user scrolls down the page.
## Installation
- With NPM:
```bash
npm install @penguin32/asa --save
```
- With Yarn:
```bash
yarn add @penguin32/asa
```
in your Angular project.
## Usage
- Import the `AsaModule` and `BrowserAnimationsModule`/`NoopAnimationsModule` into the module wherever you want to use it:
```typescript
import {AsaModule} from '@penguin32/asa';
import {BrowserAnimationsModule} from "@angular/platform-browser/animations";
@NgModule({
imports: [
// ...
AsaModule,
BrowserAnimationsModule,
]
})
export class AppModule {
}
```
### Using included animations
This library comes with a handful of animations included. You can use them by passing the name of the animation
as a string parameter to the `[scrollAnimation]` directive. The full list of available animations is available later in this document.
- Add the `[scrollAnimation]` directive to the element you want to animate:
```html
When user scrolls to this currently invisible element
it will fade in and make it's entry to the page!
```
### Using custom animations
You can also create your own animations and use them with this library. To do so, you need to create field in your component
that will hold the animation configuration as a `AnimationMetadata[]` object. You can then pass this field to the `[scrollAnimation]` directive.
- Create a field in your component that will hold the animation configuration:
```typescript
import {animate, AnimationMetadata, keyframes, query, style} from "@angular/animations";
const customAnimationExample: AnimationMetadata[] = [
query('*', [
animate('500ms ease-out',
keyframes([
style({opacity: 0, transform: 'translateX(-100%)', offset: 0}),
style({opacity: 1, transform: 'translateX(0)', offset: 1}),
]),
),
])
];
```
- Add the `[scrollAnimation]` directive to the element you want to animate:
```html
Custom Animation example
This is a very cool way to animate-in a element into the page!
```
### Bind animation progress to scroll position
You can also bind the animation progress to the scroll position. This is a cool way to animate-in and out elements as user scrolls up and down the page.
- Add the `[progressBoundToScroll]` input to the element you want to animate:
```html
This element will animate-in and out as user scrolls up and down the page
This is awesome!
```
If `[progressBoundToScroll]` is set to `false`, the animation will be triggered only once and will not be triggered again as user scrolls up and down the page,
and the element will stay visible once animated.
If the `[progressBouldToScroll]` is set to `true`, both `[animationStart]` and `[animationEnd]` will be used, as the animation is bound to the scroll position.
On the other hand, if it's set to `false`, only `[animationStart]` will be used, as the animation will be triggered when the element is `animationStart` pixels
from the bottom of the page.
## Available settings
| Directive | Type | Required | Default | Description |
|-------------------------|--------------------------------|-----------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [scrollAnimation] | `string` `AnimationMetadata[]` | Yes | `undefined` | Name of the included animation to use or custom Angular animation. |
| [progressBoundToScroll] | `boolean` | No | `false` | If set to `true`, the animation progress (0 - 100%) will be bound to the scroll position (`[animationStart]` - `[animationEnd]`), otherwise the animation will trigger only once on `[animationStart]` |
| [animationStart] | `number` | No | `200` | Distance from the bottom of the page when the animation should trigger. |
| [animationEnd] | `number` | No | `220` | Distance from the bottom of the page when the animation should end. Used only when `[progessBoundToScroll]` is `true`. |
| [duration] | `string` | No | `'500ms'` | Duration of the animation in CSS time. |
| [curve] | `string` | No | `'ease-out'` | CSS curve of the animation to be used |
## Included animations
### Fade
- `fadeIn`
- `fadeInLeft`
- `fadeInRight`
- `fadeInTop`
- `fadeInBottom`
### Flip
- `flipLeft`
- `flipRight`
- `flipTop`
- `flipBottom`
### Zoom
- `zoomIn`
- `zoomOut`
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please check CONTRIBUTING.md for more details.