Guide

Getting started

Install @samline/scroll-to with a package manager or a script tag and make your same-page links scroll smoothly below a fixed header.

Install @samline/scroll-to, then follow the Package / ESM or the HTML / CDN path to the first links. Both use the same API.

Requirements

  • Any modern browser. Without JavaScript, links still jump to their sections.
  • On the server, scrollTo resolves to false and autoScrollTo does nothing.
  • No runtime dependencies.

Install

npm

Terminal
npm install @samline/scroll-to

pnpm

Terminal
pnpm add @samline/scroll-to

yarn

Terminal
yarn add @samline/scroll-to

bun

Terminal
bun add @samline/scroll-to

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js" defer></script>

Package / ESM

import { autoScrollTo } from '@samline/scroll-to'

autoScrollTo({ offset: '#header' })
<header id="header">
  <a href="#pricing">Pricing</a>
</header>

<section id="pricing">…</section>
<button type="button" data-scroll-to="top">Back to top</button>

autoScrollTo() handles clicks on same-page #id links and [data-scroll-to] elements with one delegated listener, so links added later work too. It returns { destroy }. To scroll from your own code, await scrollTo(target, options). Available as ESM and CommonJS (require('@samline/scroll-to')). There is no stylesheet.

HTML / CDN

For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It handles links as soon as the DOM is ready. Pin the version in production.

<script
  src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"
  defer
></script>

To pass options, add data-manual to the script tag and start it yourself, or call ScrollTo.auto() from a script that runs before the DOM is ready (a deferred or inline script after the bundle):

<script
  src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"
  data-manual
  defer
></script>
<script type="module">
  ScrollTo.auto({ offset: '#header', duration: 600 })
</script>

Working starter files

A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.

Fixed headerLive preview

Same-page links scroll smoothly and stop below the header, move focus to the section and add a history entry, so Back works. The header height is read live.

Features

Lands just below the bar, and focus moves here.

Pricing

Lands just below the bar, and focus moves here.

FAQ

Lands just below the bar, and focus moves here.

Explore the code

HTML / CDN

HTML

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Anchors that land below a fixed header</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <header id="header">
        <nav>
          <a href="#features">Features</a>
          <a href="#pricing">Pricing</a>
          <a href="#faq">FAQ</a>
        </nav>
      </header>
      <main>
        <section id="features">
          <h2>Features</h2>
        </section>
        <section id="pricing">
          <h2>Pricing</h2>
        </section>
        <section id="faq">
          <h2>Faq</h2>
        </section>
        <button type="button" data-scroll-to="top">Back to top</button>
      </main>
    </main>
    <script src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"></script>
    <script src="./main.js" defer></script>
  </body>
</html>

CSS

style.css
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
header {
  position: fixed;
  inset: 0 0 auto;
  z-index: 1;
  padding: 1rem 1.5rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
nav {
  display: flex;
  gap: 1rem;
}
main {
  padding: 5rem 1.5rem 50vh;
}
section {
  min-height: 70vh;
  border-top: 1px solid #ddd;
}
section:focus {
  outline: none;
}

JavaScript

main.js
// Called before the DOM is ready, this replaces the automatic start.
ScrollTo.auto({ offset: '#header' })

Complete file

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Anchors that land below a fixed header</title>
    <style>
      body {
        margin: 0;
        font-family: system-ui, sans-serif;
      }
      header {
        position: fixed;
        inset: 0 0 auto;
        z-index: 1;
        padding: 1rem 1.5rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      nav {
        display: flex;
        gap: 1rem;
      }
      main {
        padding: 5rem 1.5rem 50vh;
      }
      section {
        min-height: 70vh;
        border-top: 1px solid #ddd;
      }
      section:focus {
        outline: none;
      }
    </style>
  </head>
  <body>
    <main>
      <header id="header">
        <nav>
          <a href="#features">Features</a>
          <a href="#pricing">Pricing</a>
          <a href="#faq">FAQ</a>
        </nav>
      </header>
      <main>
        <section id="features">
          <h2>Features</h2>
        </section>
        <section id="pricing">
          <h2>Pricing</h2>
        </section>
        <section id="faq">
          <h2>Faq</h2>
        </section>
        <button type="button" data-scroll-to="top">Back to top</button>
      </main>
    </main>
    <script src="https://cdn.jsdelivr.net/npm/@samline/scroll-to@1.6.0/dist/browser/scroll-to.global.js"></script>
    <script>
      // Called before the DOM is ready, this replaces the automatic start.
      ScrollTo.auto({ offset: '#header' })
    </script>
  </body>
</html>

Package / ESM

HTML

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Anchors that land below a fixed header</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <header id="header">
        <nav>
          <a href="#features">Features</a>
          <a href="#pricing">Pricing</a>
          <a href="#faq">FAQ</a>
        </nav>
      </header>
      <main>
        <section id="features">
          <h2>Features</h2>
        </section>
        <section id="pricing">
          <h2>Pricing</h2>
        </section>
        <section id="faq">
          <h2>Faq</h2>
        </section>
        <button type="button" data-scroll-to="top">Back to top</button>
      </main>
    </main>
    <script type="module" src="./main.js"></script>
  </body>
</html>

CSS

style.css
body {
  margin: 0;
  font-family: system-ui, sans-serif;
}
header {
  position: fixed;
  inset: 0 0 auto;
  z-index: 1;
  padding: 1rem 1.5rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
nav {
  display: flex;
  gap: 1rem;
}
main {
  padding: 5rem 1.5rem 50vh;
}
section {
  min-height: 70vh;
  border-top: 1px solid #ddd;
}
section:focus {
  outline: none;
}

JavaScript

main.js
import { autoScrollTo, scrollTo } from '@samline/scroll-to'

autoScrollTo({ offset: '#header' })

Complete file

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Anchors that land below a fixed header</title>
    <style>
      body {
        margin: 0;
        font-family: system-ui, sans-serif;
      }
      header {
        position: fixed;
        inset: 0 0 auto;
        z-index: 1;
        padding: 1rem 1.5rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      nav {
        display: flex;
        gap: 1rem;
      }
      main {
        padding: 5rem 1.5rem 50vh;
      }
      section {
        min-height: 70vh;
        border-top: 1px solid #ddd;
      }
      section:focus {
        outline: none;
      }
    </style>
  </head>
  <body>
    <main>
      <header id="header">
        <nav>
          <a href="#features">Features</a>
          <a href="#pricing">Pricing</a>
          <a href="#faq">FAQ</a>
        </nav>
      </header>
      <main>
        <section id="features">
          <h2>Features</h2>
        </section>
        <section id="pricing">
          <h2>Pricing</h2>
        </section>
        <section id="faq">
          <h2>Faq</h2>
        </section>
        <button type="button" data-scroll-to="top">Back to top</button>
      </main>
    </main>
    <script type="module">
      import { autoScrollTo, scrollTo } from '@samline/scroll-to'

      autoScrollTo({ offset: '#header' })
    </script>
  </body>
</html>

Next steps