- Docs
- Getting started
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,
scrollToresolves tofalseandautoScrollTodoes nothing. - No runtime dependencies.
Install
npm
npm install @samline/scroll-topnpm
pnpm add @samline/scroll-toyarn
yarn add @samline/scroll-tobun
bun add @samline/scroll-toHTML / CDN
<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.
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.
Explore the code
HTML / CDN
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
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
// Called before the DOM is ready, this replaces the automatic start.
ScrollTo.auto({ offset: '#header' })
Complete file
<!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
<!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
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
import { autoScrollTo, scrollTo } from '@samline/scroll-to'
autoScrollTo({ offset: '#header' })
Complete file
<!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
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of scrollTo, scrollPosition, cancelScroll, autoScrollTo and window.ScrollTo.
Options and attributes.
Layouts and focusFixed headers, skip links, containers, tabs and history.
Accessibility and motionFocus, reduced motion and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and client-side routers.