highlight-scroll/README.md

A lightweight and efficient Scroll Highlight plugin for Alpine.js, helping you track active sections on scroll.

# Highlight Scroll (Alpine.js Plugin)

Alpine.js plugin for scroll-based navigation. Highlights items as their section appears in view and scrolls smoothly on click.

---

## Installation

### CDN

```html
<script defer src="https://unpkg.com/highlight-scroll@latest/dist/highlight-scroll.min.js"></script>
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
```

### NPM/Yarn

```bash
npm install -D highlight-scroll
# or
yarn add -D highlight-scroll
```

```js
import Alpine from 'alpinejs'
import HighlightScroll from 'highlight-scroll'

Alpine.plugin(HighlightScroll({
  offset: 100,
  highlightClasses: 'text-blue-500 font-bold transition-all'
}))

Alpine.start()
```

---

## Basic Usage

```html
<main x-scroll-group>
  <div x-scroll-container>
    <section x-scroll-section="'section-1'">Section 1</section>
    <section x-scroll-section="{ id: 'section-2', group: 'default' }">Section 2</section>
  </div>

  <nav>
    <ul>
      <li><a x-scroll-item="'section-1'" href="#section-1">Section 1</a></li>
      <li><a x-scroll-item="{ target: 'section-2', group: 'default' }" href="#section-2">Section 2</a></li>
    </ul>
  </nav>
</main>
```

---

## Directives Overview

| Directive            | Purpose                              | Example                                                 |
|----------------------|--------------------------------------|---------------------------------------------------------|
| `x-scroll-group`     | Group for scroll behavior            | `x-scroll-group="{ group: 'nav', offset: 50 }"`         |
| `x-scroll-container` | Scrollable area                      | `x-scroll-container="{ group: 'default' }"`             |
| `x-scroll-section`   | Marks section (needs `id`)           | `x-scroll-section="{ id: 'about', group: 'default' }"`  |
| `x-scroll-item`      | Nav link to section                  | `x-scroll-item="{ target: 'about', group: 'default' }"` |

You can also pass simple strings:  
`x-scroll-section="'about'"` or `x-scroll-item="'about'"` (defaults to group `"default"`).

---

## Notes

- If `x-scroll-container` is not set, scrolls on `window`.
- Group is optional; defaults to `"default"`.
- Section `id` must match the item’s `target`.

---

## Author

- 🔗 [pinkary.com/@namu](https://pinkary.com/@namu)
- 💼 [LinkedIn - Namu Makwembo](https://www.linkedin.com/in/namu-makwembo/)
- 📹 [Youtube - Namu Makwembo](https://www.youtube.com/@namumakwembo/)