# scrollen

> A performant utility scroll hook for React

Latest version **0.0.2** (published 2023-06-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install scrollen
pnpm add scrollen
yarn add scrollen
bun add scrollen
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2023-06-13 |
| First published | 2023-06-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 5.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | joaom00 |
| Maintainers | joaom00 |
| Keywords | react, scroll, hook |

## Links

- npm: https://www.npmjs.com/package/scrollen
- Repository: https://github.com/joaom00/scrollen
- Homepage: https://github.com/joaom00/scrollen#readme
- Issues: https://github.com/joaom00/scrollen/issues
- npm.io page: https://npm.io/package/scrollen

## Dependencies (3)

- [@ariakit/core](https://npm.io/package/@ariakit/core.md) 0.2.5
- [@changesets/cli](https://npm.io/package/@changesets/cli.md) ^2.26.1
- [@ariakit/react-core](https://npm.io/package/@ariakit/react-core.md) 0.2.9

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.0.2 (latest) — 2023-06-13
- 0.0.1 — 2023-06-13

## README

<p align="center">
<img src="./website/public/og.png" />
</p>

# Scrollen

A performant utility scroll hook for React.

## Install

```sh
npm install scrollen
```

## Getting Started

To start using the scrollen you need import and call the `useScroller` hook

```js
import { useScroller } from 'scrollen'

const scroller = useScroller()
```

And that's it! By default the hook will listen to scroll on document.

If you want to use a different scroll container, you can use the `setScrollerElement` function

```jsx
import { useScroller } from 'scrollen'

const scroller = useScroller()

<div ref={scroller.setScrollerElement}>
  ...
</div>
```

### Example

See this [small example](https://github.com/joaom00/scrollen/blob/main/website/src/app/page.tsx) of how you can use the hook.

## Documentation

First of all, a huge thanks to [@diegohaz](https://twitter.com/diegohaz) as this library uses the
Ariakit Component Stores API, so refer to the Ariakit [Component Stores Guide](https://ariakit.org/guide/component-stores) to learn the core
of the hook.

### Props

| Prop                | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `initialScrollTop`  | The initial `scrollTop` value to the scroller element.         |
| `initialScrollLeft` | The initial `scrollLeft` value to the scroller element.        |
| `startScrollAt`     | Where the scroll should start. You can pass `bottom \| right`. |

### State

| State              | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `element`          | The scroller element.                                               |
| `scrollTop`        | The `scrollTop` value for the scroller element.                     |
| `scrollLeft`       | The `scrollLeft` value for the scroller element.                    |
| `scrollWidth`      | The `scrollWidth` value for the scroller element.                   |
| `scrollHeight`     | The `scrollHeight` value for the scroller element.                  |
| `scrollY`          | The progress of the vertical scroll. (between 0 and 1)              |
| `scrollX`          | The progress of the horizontal scroll. (between 0 and 1)            |
| `scrollLengthY`    | The length of the vertical scroll.                                  |
| `scrollLengthX`    | The length of the horizontal scroll.                                |
| `scrollDirectionY` | The direction of the vertical scroll. (`static \| up \| down`)      |
| `scrollDirectionX` | The direction of the horizontal scroll. (`static \| left \| right`) |
| `isAtTop`          | A boolean to check if the scroll reached the top.                   |
| `isAtBottom`       | A boolean to check if the scroll reached the bottom.                |
| `isAtLeft`         | A boolean to check if the scroll reached the left.                  |
| `isAtRight`        | A boolean to check if the scroll reached the right.                 |

### Functions

| Function             | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| `setScrollerElement` | Function to set the scroller element.                                                   |
| `scrollToTop`        | Function to scroll programatically to top.                                              |
| `scrollToLeft`       | Function to scroll programatically to left.                                             |
| `scrollToBottom`     | Function to scroll programatically to bottom.                                           |
| `scrollToRight`      | Function to scroll programtically to right.                                             |
| `useOnScrollTop`     | A custom hook to register a callback that is called when the scroll reached the top.    |
| `useOnScrollBottom`  | A custom hook to register a callback that is called when the scroll reached the bottom. |

## Acknowledgements

- Ariakit - Thanks to [@diegohaz](https://twitter.com/diegohaz) for the Component Stores API that
  made it possible to create a performant hook.
- react-virtuoso - Where did I get ideas for utilities.

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