# magical-scroll

> ## Basic Usage

Latest version **1.0.15** (published 2024-05-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install magical-scroll
pnpm add magical-scroll
yarn add magical-scroll
bun add magical-scroll
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.15 |
| Published | 2024-05-29 |
| First published | 2022-09-29 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 41.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Eli Lin |
| Maintainers | eli2n |
| Keywords | js, javascript, parallax, scroll |

## Links

- npm: https://www.npmjs.com/package/magical-scroll
- Repository: https://github.com/L-Eli/magical-scroll
- Homepage: https://github.com/L-Eli/magical-scroll#readme
- Issues: https://github.com/L-Eli/magical-scroll/issues
- npm.io page: https://npm.io/package/magical-scroll

## Dependencies (1)

- [@babel/core](https://npm.io/package/@babel/core.md) ^7.24.6

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.15 (latest) — 2024-05-29
- 1.0.14 — 2024-05-29
- 1.0.13 — 2024-05-24
- 1.0.12 — 2024-05-18
- 1.0.11 — 2022-10-20
- 1.0.10 — 2022-10-20
- 1.0.9 — 2022-10-20
- 1.0.8 — 2022-10-20
- 1.0.7 — 2022-10-08
- 1.0.6 — 2022-10-06
- 1.0.5 — 2022-10-06
- 1.0.4 — 2022-10-05
- 1.0.3 — 2022-09-29
- 1.0.2 — 2022-09-29
- 1.0.1 — 2022-09-29
- … 1 more at https://npm.io/package/magical-scroll/versions

## README

# Magical Scroll

## Basic Usage

```javascript=
MagicalScroll.getInstance().addElement({
  target: "#scroll",
  animations: {
    opacity: {
      positions: [0, 100],
      values: [0, 1],
    },
  },
});
```

## Magic Slugs

| Slug | Description |
| - | - |
| #screenWidth | width of the screen |
| #screenHeight | height of the screen |
| #scrollWidth | width of the scroll container |
| #scrollHeight | height of the scroll container |
| #elementWidth | width of the element |
| #elementHeight | height of the element |
| #elementIn | when the element appear at the bottom of the container |
| #elementOut | when the element disappear at the top of the container |
| #elementCenter | when the element is placed center of the container |
| #parentElementWidth | width of the parent element (node) |
| #parentElementHeight | height of the parent element (node) |
| #parentElementIn | when the parent element (node) appear at the bottom of the container |
| #parentElementOut | when the parent element (node) disappear at the top of the container |
| #parentElementCenter | when the parent element (node) is placed center of the container |
| #ancestorElementWidth{1} | width of the ancestor element (node), where `{1}` means the generation(s) |
| #ancestorElementHeight{1} | height of the ancestor element (node), where `{1}` means the generation(s) |
| #ancestorElementIn{1} | when the ancestor element (node) appear at the bottom of the container, where `{1}` means the generation(s) |
| #ancestorElementOut{1} | when the ancestor element (node) disappear at the top of the container, where `{1}` means the generation(s) |
| #ancestorElementCenter{1} | when the ancestor element (node) is placed center of the container, where `{1}` means the generation(s) |

## Built-in Properties

| Name | Description |
| - | - |
| opacity ||
| scale ||
| rotate ||
| translateX ||
| translateY ||
| display | `none` or just nothing |
| visibility | `visible` or `hidden` |
| backgroundColor | calculating within values |
| color | calculating within values |

## Register/Replace your own property

### Register/Replace the value populating callback

```javascript=
const magicalScroll = MagicalScroll.getInstance();
const animationName = "myScrollAnimation";
magicalScroll.registerPropertyPopulateCallback(
  animationName,
  (currentPosition, positions, values) => {
    const index = positions.findIndex((position) => position > currentPosition);
    return index > -1 ? values[index] : values[values.length - 1];
  },
);
```

Explanation

| Name | Meaning |
| - | - |
| currentPosition | current scroll top of the container |
| positions | list of position which are already computed as a number |
| values | list of value |

You can also register a new animation with existed built-in callback

```javascript=
const magicalScroll = MagicalScroll.getInstance();
const animationName = "opacity";
magicalScroll.registerPropertyPopulateCallback(
  animationName,
  MagicalScroll.populateNumberValueCallback,
);
```

### Register/Replace the CSS generation callback

```javascript=
const magicalScroll = MagicalScroll.getInstance();
const animationName = "myScrollAnimation";
magicalScroll.registerPropertyPopulateCallback(
  animationName,
  (target, property, value) => {
    target.style.display = value ? null : "none";
  }
);
```

Explanation

| Name | Meaning |
| - | - |
| target | element target |
| property | name of the property, `animationName` as the example above |
| value | computed value |

## What the next?

1. Provide other properties something like `skew`, `brightness`.
2. `Interaction Observer API` for better performance.
3. Support multiple instances.
4. Child slug.
5. Query for element.
6. Function of toggling class by position.
7. Inertia?
8. Animation function (ease-in-out, ... etc.) support.
9. Refactor it into better architecture.
10. `Matrix` calculation.

---
_Source: https://npm.io/package/magical-scroll · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._