View on GitHub

Back to top

Sticky back-to-top link appearing after scrolling down one viewport height.

On this page

Overview

Boosted "back to top" provides a way to get back to the top of the page using a simple link. It’s built only with HTML and CSS, meaning you don’t need any JavaScript. It only requires a .back-to-top wrapper and a .back-to-top-link, at the end of your body— just before your scripts.

For accessibility purposes, back-to-top link contains a .visually-hidden text content and a data-bs-label attribute— whose value should match hidden text content to make sure it’s usable with speech recognition software. The data-bs-label attribute content is displayed in a ::before pseudo-element thanks to the attr() CSS function.

We also recommend using a nav wrapper —alongside an accurate aria-label— to ease discoverability through landmarks.

Make sure you leave enough space between the back-to-top link and the bottom of the viewport to:

  • prevent the component being overlapped by bottom navigation bar on mobile and notification tooltips for Windows users,
  • avoid proximity with system interactive areas, which could lead to accidentally activating an adjacent target.

Smooth scroll

Smooth scrolling does not depend on this component. It’s turned on only when the user has not explicitly signaled that they’d prefer reduced motion (i.e. where prefers-reduced-motion: no-preference) through the scroll-behavior property. Read more about prefers-reduced-motion in our accessibility page.

Example

<nav aria-label="Back to top" class="back-to-top">
  <a href="#top" class="back-to-top-link btn btn-icon btn-outline-secondary" data-bs-label="Back to top">
    <span class="visually-hidden">Back to top</span>
  </a>
</nav>
html

Define a target

Since we’re using a link, you need a valid target. We recommend adding an anchor link at the beginning of your markup, like so: <a id="top"></a>. You may use another id, but if you’re using a fixed header you’ll need to override our $back-to-top-target-id variable to ensure it won’t overlap content after scrolling up.

Always visible

Add .position-fixed utility to your .back-to-top-link to make your back-to-top link persistent.

<nav aria-label="Fixed back to top example" class="back-to-top">
  <a href="#top" class="back-to-top-link position-fixed btn btn-icon btn-outline-secondary" data-bs-label="Back to top">
    <span class="visually-hidden">Back to top</span>
  </a>
</nav>
html

Icon only

Use a title attribute instead of data-bs-label to ensure a visible label is still provided on demand for sighted users.

<nav aria-label="Back to top" class="back-to-top">
  <a href="#top" class="back-to-top-link btn btn-icon btn-outline-secondary" title="Back to top">
    <span class="visually-hidden">Back to top</span>
  </a>
</nav>
html

CSS

Variables

Added in v5.2.0

As part of Boosted’s evolving CSS variables approach, Back to tops now use local CSS variables on .back-to-top for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

scss/_back-to-top.scss 
--#{$prefix}back-to-top-top: #{$back-to-top-display-threshold};
--#{$prefix}back-to-top-right: #{$back-to-top-offset-right};
--#{$prefix}back-to-top-bottom: #{$back-to-top-offset-bottom};
--#{$prefix}back-to-top-zindex: #{$zindex-back-to-top};
--#{$prefix}back-to-top-link-offset-top: #{$back-to-top-link-offset-top};
--#{$prefix}back-to-top-link-icon: #{$back-to-top-icon};
--#{$prefix}back-to-top-link-width: #{$back-to-top-icon-width};
--#{$prefix}back-to-top-link-height: #{$back-to-top-icon-height};
--#{$prefix}back-to-top-link-bg: #{$back-to-top-bg};
--#{$prefix}back-to-top-title-offset-right: #{$back-to-top-title-offset-right};
--#{$prefix}back-to-top-title-padding: #{$back-to-top-title-padding};
--#{$prefix}back-to-top-title-color: #{$back-to-top-title-color};
--#{$prefix}back-to-top-title-bg-color: #{$back-to-top-title-bg-color};
--#{$prefix}back-to-top-title-active-decoration: #{$link-decoration};

As it is a responsive component, here is the overridden variables in xl breakpoint:

scss/_back-to-top.scss 
@include media-breakpoint-up(xl) {
  --#{$prefix}back-to-top-right: #{$back-to-top-offset-right * 2};
  --#{$prefix}back-to-top-bottom: #{$back-to-top-offset-bottom * 2};
  --#{$prefix}back-to-top-link-offset-top: #{$back-to-top-link-offset-top-xl};
}

Sass options

Back to top link can be customized in a few ways: either making it appear after more or less vertical scrolling, modify its offset from the bottom right corner, etc.

VariableDescriptionDefault
$back-to-top-display-threshold

Defines the vertical threshold at which "back to top" link appears.

100vh
$back-to-top-target-id

Target’s id, used to apply scroll-margin-top when anchor is active.

"top"
$back-to-top-offset

Base offset, used to place "back to top" link in the bottom right corner of the page.

$spacer * 1.5

Sass variables

For more details, please have a look at the exhaustive list of available variables:

scss/_variables.scss 
$back-to-top-display-threshold:  100vh;
$back-to-top-target-id:          "top";
$back-to-top-target-offset-top:  $scroll-offset-top;
$back-to-top-offset:             $spacer * 1.5;
$back-to-top-offset-right:       $back-to-top-offset;
$back-to-top-offset-bottom:      $back-to-top-offset;
$back-to-top-link-offset-top:    subtract(100vh, $back-to-top-offset * 4);
$back-to-top-link-offset-top-xl: subtract(100vh, $spacer * 5);
$back-to-top-title-offset-right: add(100%, var(--#{$prefix}border-width));
$back-to-top-title-padding:      subtract($btn-padding-y, 1px) $btn-padding-x add($btn-padding-y, 1px);
$back-to-top-title-color:        var(--#{$prefix}body-color);
$back-to-top-title-bg-color:     var(--#{$prefix}body-bg);
$back-to-top-bg:                 var(--#{$prefix}highlight-color);
$back-to-top-icon:               var(--#{$prefix}chevron-icon);
$back-to-top-icon-width:         add(.5rem, 1px);
$back-to-top-icon-height:        subtract(1rem, 1px);