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 group 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 Readtime Scheme toggle Select Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionAlertCall 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

Provides a fixed-position anchor link for scrolling back to the top of long pages. Appears after a configurable scroll threshold; should be last in tab order. Renders an <a> element so screen readers announce it as a navigation link. Keyboard-accessible via Tab and Enter (WCAG 2.1.1). Avoid placing more than one instance per page.

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. Serves as the ARIA accessible name for the anchor link (per WCAG 2.5.3 Label in Name). Use visible, descriptive text so screen readers announce the link purpose; avoid icon-only content without a label.
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 1

CSS Property Description Default
--rh-back-to-top-background-color —

Design Tokens 14

Token Description Copy
--rh-space-xl

Back-to-top inline-end inset

Back-to-top block-end inset

24px spacer
--rh-color-text-primary-on-dark

Trigger text color in light mode

Primary text color for dark theme
--rh-color-text-primary-on-light

Trigger text color in dark mode

Primary text color for light theme
--rh-color-accent-base

Trigger background color
--rh-space-md

Trigger horizontal spacing

8px spacer
--rh-border-radius-pill

Trigger border radius

Pill border radius; Example: Label
--rh-space-xs

Trigger vertical spacing

Trigger content gap

4px spacer
--rh-line-height-body-text

Trigger line height

Line height for body text
--rh-border-width-md

Trigger outline width

Trigger border width

Trigger hover/focus outline width

Trigger hover/focus border width

2px border width: Example: Alert
--rh-color-border-strong-on-dark

Trigger hover/focus border color in light mode

Strong border color (dark theme)
--rh-color-border-strong-on-light

Trigger hover/focus border color in dark mode

Strong border color (light theme)
--rh-color-interactive-primary-hover

Trigger hover/focus outline color

Trigger hover/focus background color
--rh-font-size-body-text-xs

Trigger text size

12px font size
--rh-space-3xl

Back-to-top inline-end inset at viewport >= md

Back-to-top block-end inset at viewport >= md

48px spacer

Other libraries

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