Back to Top

SBackTop is a floating button that shows up once the page has been scrolled and takes the visitor back to the top. By default it watches the window; point target at a CSS selector to follow a scrollable container instead.

The control is a real <button>, so it is reachable with the keyboard and announced as a button. Its accessible name comes from the locale dictionary (backToTop — "Back to top"): set label to override it on one instance, or replace the dictionary entry through ConfigProvider to change it everywhere. Scrolling is animated unless the visitor has asked the system for reduced motion, in which case the jump is instant.

The button is position: fixed. Every example below follows its own scrollable box and sits in a wrapper with a transform, which makes that wrapper the containing block — otherwise the button would float over the documentation instead of staying inside the example.

Following a container

Scroll down inside this box — the button appears after 200px.

<template>
  <div id="page-body">…</div>
  <SBackTop target="#page-body" />
</template>

Without target the component listens to the window, which is what a long article page needs:

<template>
  <SBackTop />
</template>

Threshold and placement

visibilityHeight is the scroll distance in pixels after which the button appears. The offsets from the corner are CSS custom properties — --s-back-top-right and --s-back-top-bottom, both 1.5rem by default — so the button can be moved without overriding any rule. The button itself takes the size, variant, color and round props straight to SButton.

The button appears after 50px and sits closer to the corner.

<template>
  <SBackTop
    target="#page-body"
    :visibility-height="50"
    size="sm"
    variant="secondary"
    :round="false"
    style="--s-back-top-right: 12px; --s-back-top-bottom: 12px"
  />
</template>

Custom control

The default slot replaces the button and receives visible and scrollToTop, so any control can drive the same behavior. It is still hidden and revealed by the component, and it still has to be focusable and carry an accessible name of its own.

Scroll down for a labelled button.

<template>
  <SBackTop
    target="#page-body"
    :visibility-height="50"
  >
    <template #default="{ scrollToTop }">
      <SButton
        variant="secondary"
        icon="chevron-up"
        @click="scrollToTop"
      >
        Back to top
      </SButton>
    </template>
  </SBackTop>
</template>

API

Props

Name	Type	Default	Description
target	string	undefined	CSS selector of the scrollable container to watch and scroll. Without it the component follows the window. The selector is resolved once, when the component mounts.
visibility-height	number	200	Scroll distance in pixels after which the button appears.
behavior	"smooth" | "auto"	"smooth"	Scrolling behavior: animated (smooth) or instant (auto). smooth turns into auto for visitors whose system asks for reduced motion.
icon	string	"chevron-up"	Button icon: a registry name or a raw SVG path.
label	string	undefined	Accessible name of the button. Defaults to the locale dictionary entry (backToTop).
size	"md" | "sm" | "lg"	"md"	Button size: sm (32px), md (40px) or lg (48px).
variant	| "primary" | "secondary" | "negative" | "outline" | "ghost"	"primary"	Visual variant of the button: filled primary/secondary/negative, outlined outline or transparent ghost.
color	string	undefined	Accent color: a name from the palette (primary/teal/teal-10). Overrides the variant color.
round	boolean	true	Circular button. Set false for a rounded square.

Slots

Name	Description
default	Replaces the button. Receives the current visibility and the scroll action, so a custom control can drive the same behavior.