@preline/scroll-nav

Scroll Nav

Scroll Nav is a versatile and lightweight JavaScript plugin designed to enhance navigation menus with smooth scrolling capabilities.

Contents

• Overview
• Installation
• Basic usage
• Configuration Options
• JavaScript API
• Common Patterns
• License

Overview

The Scroll Nav component provides horizontal scrolling navigation with previous/next buttons and automatic centering. It's ideal for navigation menus with many items that need to be scrolled horizontally.

Key Features:

• Horizontal scrolling navigation
• Previous/next navigation buttons
• Automatic centering of active items
• Programmatic control via JavaScript API
• Smooth scrolling animations
• Current state tracking

Installation

To get started, install Scroll Nav plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i @preline/scroll-nav

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/scroll-nav */
@source "../node_modules/@preline/scroll-nav/*.js";
@import "./node_modules/@preline/scroll-nav/variants.css";
@import "./node_modules/@preline/scroll-nav/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/@preline/scroll-nav/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script type="module">
  import HSScrollNav from "@preline/scroll-nav/non-auto.mjs";

  new HSScrollNav(document.querySelector("#scroll-nav"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

@preline/scroll-nav is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import "@preline/scroll-nav";

@preline/scroll-nav/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import HSScrollNav from "@preline/scroll-nav/non-auto";

HSScrollNav.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#scroll-nav");
if (el) new HSScrollNav(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a scroll nav component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The navigation items scroll horizontally with previous/next buttons.

<div data-hs-scroll-nav class="relative px-6">
  <button type="button" class="hs-scroll-nav-prev">Previous</button>

  <nav class="hs-scroll-nav-body flex flex-nowrap overflow-x-auto snap-x snap-mandatory">
    <a class="snap-start" href="#">Electronics</a>
    <a class="snap-start" href="#">Clothing</a>
    <a class="snap-start" href="#">House & Garden</a>
    <a class="snap-start" href="#">Baby Care</a>
    <a class="snap-start" href="#">Home appliances</a>
    <a class="snap-start" href="#">Sports & Fitness</a>
    <a class="snap-start" href="#">Constraction & Renovation</a>
    <a class="snap-start" href="#">Food</a>
    <a class="snap-start" href="#">Pharmacy</a>
    <a class="snap-start" href="#">Pet Products</a>
    <a class="snap-start" href="#">Books</a>
    <a class="snap-start" href="#">Tourism, fishing, hunting</a>
    <a class="snap-start" href="#">Furniture</a>
    <a class="snap-start" href="#">Jewelery</a>
    <a class="snap-start" href="#">Accessories</a>
    <a class="snap-start" href="#">Games & Consoles</a>
    <a class="snap-start" href="#">Stationery</a>
    <a class="snap-start" href="#">Digital Goods</a>
    <a class="snap-start" href="#">Music</a>
  </nav>

  <button type="button" class="hs-scroll-nav-next">Next</button>
</div>

Structure Requirements:

• data-hs-scroll-nav: Required on the container element
• hs-scroll-nav-prev: Required class on the previous button
• hs-scroll-nav-next: Required class on the next button
• hs-scroll-nav-body: Required class on the scrollable navigation container
• Navigation items inside the scrollable container

Initial State:

• Navigation items are visible
• Previous/next buttons are enabled/disabled based on scroll position
• Active item can be centered automatically if autoCentering is enabled

Configuration Options

Data Options

Data options are specified in the data-hs-scroll-nav attribute.

Example:

<div data-hs-scroll-nav='{
  "autoCentering": true
}'>
  <!-- Navigation structure -->
</div>

Required CSS Classes

These classes define the structure and must be present for the scroll nav to function.

Tailwind Modifiers

JavaScript API

The HSScrollNav object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a scroll nav instance.

Static Methods

These methods are called directly on the HSScrollNav class.

Usage Examples

Example 1: Getting current state

// Get the scroll nav instance
const instance = HSScrollNav.getInstance('#hs-scroll-nav', true);

if (instance) {
  const { element } = instance;
  // Get current state
  const state = element.getCurrentState();

  console.log('First visible:', state.first);
  console.log('Last visible:', state.last);
  console.log('Center visible:', state.center);
}

Example 2: Scrolling to an element

const instance = HSScrollNav.getInstance('#hs-scroll-nav', true);

if (instance) {
  const { element } = instance;
  const targetLink = document.querySelector('#hs-e-commerce-link');

  // Scroll to element
  element.goTo(targetLink, () => {
    console.log('Scrolled to element!');
    // Perform actions after scrolling
  });
}

Example 3: Centering an element

const instance = HSScrollNav.getInstance('#hs-scroll-nav', true);

if (instance) {
  const { element } = instance;
  const targetLink = document.querySelector('#hs-e-commerce-link');

  // Center element
  element.centerElement(targetLink, 'smooth');
}

Example 4: Destroying scroll nav instance

const instance = HSScrollNav.getInstance('#hs-scroll-nav', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-scroll-nav').remove();
  });
}

Common Patterns

Pattern 1: Auto-centering Active Item

Automatically center the active item on page load.

<div data-hs-scroll-nav='{
  "autoCentering": true
}'>
  <!-- Navigation structure -->
</div>

Pattern 2: Programmatic Navigation

Control navigation programmatically.

<div id="hs-scroll-nav-first" data-hs-scroll-nav>
  <!-- Navigation structure -->
</div>

<script>
  const instance = HSScrollNav.getInstance('#hs-scroll-nav-first', true);
  if (instance) {
    const { element } = instance;
    // Scroll to specific item
    const item = document.querySelector('#hs-item-electronics');
    
    element.goTo(item);
  }
</script>

License

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.