Back-to-top
Floating button that scrolls the page to the top. Works as a plain anchor link without JavaScript and upgrades to a show-on-threshold floating button with smooth scroll when JS is available.
Usage
When to use
- On long pages where users may scroll far and need a quick way back
- On article, documentation, and report pages
When not to use
- On short pages where the top is always within a short scroll
- When a persistent sticky header already provides easy access to primary navigation
- Inside modals or drawers - use in-container scroll affordances instead
Do
- Place consistently in the same screen position across the site
- Provide a visible focus ring
- Ensure the control respects reduced-motion preferences
Don't
- Animate the scroll without checking
prefers-reduced-motion - Use an icon-only control without an accessible name
- Obscure other fixed controls (chat widgets, cookie banners)
API
Slots
| Slot | Required | Description |
|---|---|---|
content | Yes | Visible text content (e.g. "Back to top"). |
icon | - | Pre-rendered icon to display alongside or instead of the text. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
is_enhanced | boolean | - | When true, adds the scroll-threshold data attribute for show/hide behavior. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Examples
Text
Text-only "Back to top" link.
Icon and text
Combined icon + text variant.
Icon only
Icon without visible text, where the accessible name comes from the link's aria-label.
Enhanced
Scrollspy-driven variant that stays hidden until the page has scrolled past its 300px threshold. Scroll the canvas to bring it in.
Accessibility
- WCAG 2.2 AA
- Icon-only variant must provide an accessible name (
aria-label="Back to top"). - Visible focus ring when keyboard-focused
- Smooth scroll respects
prefers-reduced-motion- falls back to an instant jump. - Keyboard reachable and operable with Enter / Space
Progressive enhancement
- No JS: renders as a visible anchor link pointing to
#top(or the top of the page) - With JS: shows/hides on a scroll threshold and performs a smooth scroll to the top
- How to enable: include the back-to-top JS enhancement
Related
- header - sticky headers are an alternative pattern for reaching primary navigation quickly