Neanderthals Paint Mammals


    1.3.4 • Public • Published

    NPM version Build status License Documentation



    Apply smooth scroll to anchor links to polyfill the CSS property scroll-behavior



    • 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) to work!


    Browser support

    IE / EdgeIE / Edge FirefoxFirefox ChromeChrome SafariSafari iOS SafariiOS Safari OperaOpera
    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



    1. Set scroll-behavior: smooth in CSS

    Has to be set global (on html), check the docs for limitations


    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:

    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:

    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, so you can write regular CSS and it'll be transformed to work with the polyfill automatically.
    The plugin will also read your 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 style="scroll-behavior: smooth;">
    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 {
        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 works, but you can just as well use another one or write your own implementation. Learn More

    2a. From a CDN

    <script src=""></script>

    2b. From npm

    npm install smoothscroll-anchor-polyfill


    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
    The documentation site itself is built as a smooth scrolling one-page design, utilizing this polyfill.


    PRs welcome!


    © 2021, Jonas Kuske


    npm i smoothscroll-anchor-polyfill

    DownloadsWeekly Downloads






    Unpacked Size

    59.4 kB

    Total Files


    Last publish


    • jonaskuske