https://github.com/jonaskuske/smoothscroll-anchor-polyfill
⚓ Apply smooth scroll to anchor links, polyfill scroll-behavior
https://github.com/jonaskuske/smoothscroll-anchor-polyfill
anchor hashchange polyfill scroll scroll-behavior smooth smooth-scroll smooth-scrolling smoothscroll smoothscroll-anchor-polyfill
Last synced: about 1 year ago
JSON representation
⚓ Apply smooth scroll to anchor links, polyfill scroll-behavior
- Host: GitHub
- URL: https://github.com/jonaskuske/smoothscroll-anchor-polyfill
- Owner: jonaskuske
- License: mit
- Created: 2018-11-10T21:01:29.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2022-08-01T14:31:05.000Z (over 3 years ago)
- Last Synced: 2025-03-28T10:21:30.983Z (about 1 year ago)
- Topics: anchor, hashchange, polyfill, scroll, scroll-behavior, smooth, smooth-scroll, smooth-scrolling, smoothscroll, smoothscroll-anchor-polyfill
- Language: JavaScript
- Homepage: https://jonaskuske.github.io/smoothscroll-anchor-polyfill
- Size: 3 MB
- Stars: 43
- Watchers: 1
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
smoothscroll-anchor-polyfill
⚓ Apply smooth scroll to anchor links to polyfill the CSS property scroll-behavior
## Features
- ✔ Smooth scroll to target when clicking an anchor
- ✔ Smooth scroll to target on hashchange (◀/▶ buttons)
- ✔ Updates URL with #fragment
- ✔ Handles focus for improved accessibility
- ✔ Doesn't break server-side rendering
- ✔ 1.3KB gzipped
⚠ Requires smooth scroll for `window.scroll()` and `Element.scrollIntoView()` (e.g. [smoothscroll-polyfill](http://iamdustan.com/smoothscroll/)) to work!
## Browser support
| [
](http://godban.github.io/browsers-support-badges/)IE / Edge | [
](http://godban.github.io/browsers-support-badges/)Firefox | [
](http://godban.github.io/browsers-support-badges/)Chrome | [
](http://godban.github.io/browsers-support-badges/)Safari | [
](http://godban.github.io/browsers-support-badges/)iOS Safari | [
](http://godban.github.io/browsers-support-badges/)Opera |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IE9+, Edge | native | native\* | last 2 versions | last 2 versions | native\* |
> \* hashchange navigation triggered by forwards/backwards buttons isn't smooth despite native support. [Learn more](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#native-inconsistencies)
## Usage
### 1. Set `scroll-behavior: smooth` in CSS
> ⚠ Has to be set global (on `html`), [check the docs for limitations](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#global-only)
Because CSS properties unknown to a browser can't efficiently be parsed from JavaScript, just specyfing the normal `scroll-behavior` property is not enough unfortunately.
You need to add an additional CSS variable so the polyfill can read it:
```css
html {
--scroll-behavior: smooth;
scroll-behavior: smooth;
}
```
You can also use media queries, toggle classes etc. to control the smooth scroll. The following only enables smooth scroll on Desktop devices, for example:
```css
html {
--scroll-behavior: auto;
scroll-behavior: auto;
}
@media screen and (min-width: 1150px) {
html {
--scroll-behavior: smooth;
scroll-behavior: smooth;
}
}
```
> 💡 This process can be automated using a [PostCSS plugin](https://github.com/jonaskuske/postcss-smoothscroll-anchor-polyfill), so you can write regular CSS and it'll be transformed to work with the polyfill automatically.
> The plugin will also read your [browserslist](https://github.com/browserslist/browserslist) and choose the right transformation depending on if all your browsers support CSS variables or not. It just works™
#### Need to support Internet Explorer?
Legacy browsers like Internet Explorer do not support CSS variables, so you need another way to specify `scroll-behavior`. There are two options:
##### Using the inline `style` attribute
```html
...
```
##### Using `font-family`
Alternatively, you can specify the property as the name of a custom font family. Your actual fonts will still work the way they should (plus, you can simply declare actual fonts on `body`). As with CSS variables (and unlike inline styles), this allows you to use normal CSS features like media queries.
```html
html {
scroll-behavior: auto;
font-family: 'scroll-behavior: auto;', 'Roboto', sans-serif;
}
```
### 2. Install the polyfill
Because this polyfill only wires up anchor links to use the browser's native `window.scroll()` and `element.scrollIntoView()` methods, you'll need to load a polyfill providing smooth scroll to these methods **in addition to the steps outlined below**.
> [smoothscroll-polyfill](http://iamdustan.com/smoothscroll/) works, but you can just as well use another one or write your own implementation. [Learn More](https://jonaskuske.github.io/smoothscroll-anchor-polyfill#usage)
#### 2a. From a CDN
```html
```
#### 2b. From npm
```bash
npm install smoothscroll-anchor-polyfill
```
then
```js
import 'smoothscroll-anchor-polyfill'
```
## Full Documentation & Demo
The full documentation with advanced installation instructions, limitations, features like enabling and disabling the smooth scrolling and more can be found at
[**jonaskuske.github.io/smoothscroll-anchor-polyfill**](https://jonaskuske.github.io/smoothscroll-anchor-polyfill).
The documentation site itself is built as a smooth scrolling one-page design, utilizing this polyfill.
---
**PRs welcome!**
© 2021, Jonas Kuske