Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Scheme toggle Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Back to top

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-back-to-topUsage guidelinesUsage guidelinesUsage guidelinesUsage guidelinesAccessibilityImportingUsagerh-back-to-topUsage guidelinesUsage guidelinesUsage guidelinesUsage guidelinesAccessibility

Importing

Add rh-back-to-top to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-back-to-top/rh-back-to-top.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Usage 

<div id="overflow">
  <p>Scroll down to reveal the back to top element</p>
  <rh-back-to-top href="#">Back to top</rh-back-to-top>
</div>

<script type="module">
  import '@rhds/elements/rh-back-to-top/rh-back-to-top.js';
</script>

<style>
  #overflow {
    min-block-size: calc(100dvh + 401px);
  }

  p {
    font-weight: bold;
  }
</style>
Copy to Clipboard Wrap lines

rh-back-to-top

Back to top component is a fragment link that allows users to quickly navigate to the top of a lengthy content page.

Customizing the background color
.custom-theme {
--rh-back-to-top-background-color: var(--custom-brand-color);
}
Slots 1
Slot Name Summary Description
[default]

link text content (default slot)

Text displayed within the back to top button. Defaults to "Back to top" if not provided. Keep text short and action-oriented. Should clearly indicate the button will navigate to the top of the page. Common alternatives include "Top", "Back to top", or localized equivalents. The text appears alongside an upward caret icon.
Note: [default] unnamed slots do not have a slot="name" attribute.
Attributes 4
Attribute DOM Property Description Type Default
visible visible

Controls the visibility behavior of the back to top button.

  • undefined (default) - Button appears automatically after scrolling past scroll-distance
  • always - Button is always visible, ignoring scroll position

Usage guidelines

  • Use the default behavior for most cases to avoid cluttering the viewport
  • Use visible="always" only for testing or special use cases where the button should be permanently visible regardless of scroll position
Always visible
<rh-back-to-top visible="always">Back to top</rh-back-to-top>
 
'always' | undefined
 
unknown
scrollable-selector scrollableSelector

CSS selector for the element to monitor for scroll events.

When not provided, the component monitors the window's scroll position (default behavior). When provided, monitors the specified element's scroll position instead.

Usage guidelines

  • Use the default (window scrolling) for standard page layouts
  • Set a selector when the main scrollable content is within a specific container element
  • The selector must point to a scrollable element (with overflow: auto or scroll)
  • Useful for single-page applications with scrollable panels
Monitor a specific container
<rh-back-to-top scrollable-selector="#main-content">Back to top</rh-back-to-top>
 
string
 
unknown
scroll-distance scrollDistance

Distance in pixels from the top of the scrollable element to trigger button visibility.

The button appears when the user scrolls past this threshold and disappears when scrolling back above it. Default is 400px.

Usage guidelines

  • Default 400px works well for most standard page layouts
  • Increase for longer pages where users need more scroll before the button appears
  • Decrease for shorter pages or containers where users reach the bottom quickly
  • Consider page fold height and content length when customizing
Custom scroll threshold
<rh-back-to-top scroll-distance="800">Back to top</rh-back-to-top>
 
number
 
400
href href

Page fragment identifier (anchor) for the target element to scroll to.

Must be a hash link pointing to an element ID on the page. The hash symbol (#) is automatically prepended if not provided.

Usage guidelines

  • The target element should be near the top of the page (typically the page title or skip link)
  • Ensure the target element has a matching id attribute
  • Common targets: #top, #main, #content, or the page's main heading ID
  • Without this attribute, clicking the button scrolls to the top of the page/container

Accessibility

  • The href creates a proper anchor link for keyboard and screen reader users
  • Provides a fallback navigation method if JavaScript is disabled
Link to page top
<rh-back-to-top href="#top">Back to top</rh-back-to-top>
 
string
 
unknown
Methods 0
None
Events 0
None
CSS Shadow Parts 1
Part Name Summary Description
trigger

anchor link that triggers scroll to top

The clickable link element that navigates to the top of the page or specified target. This part can be styled to customize the button's appearance including hover states, borders, shadows, and positioning. The button uses a pill shape with the accent color background and includes both text and an upward caret icon.
CSS Custom Properties 2
CSS Property Description Default
--rh-back-to-top-background-color —
--rh-back-to-top-background-color var(--rh-color-accent-base)
Design Tokens 14
Token Summary Copy
--rh-space-xl
--rh-color-text-primary-on-dark
--rh-color-text-primary-on-light
--rh-color-accent-base
--rh-space-md
--rh-border-radius-pill
--rh-line-height-body-text
--rh-border-width-md
--rh-color-border-strong-on-dark
--rh-color-border-strong-on-light
--rh-color-interactive-primary-hover
--rh-font-size-body-text-xs
--rh-space-xs
--rh-space-3xl

Other libraries

To learn more about our other libraries, visit the getting started page.
Edit this page on GitHub
© 2025 Red Hat Deploys by Netlify