BackTop - Semi Design Next

Demos

How to import

import { BackTop } from '@fibrous/semi-ui-react';

Basic Usage

BackTop is a FloatButton that appears once target scrolls past visibilityHeight and scrolls it back to the top when clicked. It shows a back-to-top icon by default, and its accessible name comes from the locale by default ('Back to top' in English), which aria-label can override.

Scroll down to see the bottom-right gray button.

Code

import { BackTop } from '@fibrous/semi-ui-react';

export default function BackTopDemo() {
    return (
        <div>
            <span>Scroll down to see the bottom-right gray button.</span>
            <BackTop aria-label="Back to top" />
        </div>
    );
}

Customized Style

BackTop sits 50px from the bottom and 100px from the right (the left in RTL) by default, which style can override.

Its look is customized with the FloatButton props icon, shape, size, colorful and badge.

向下滚动，右下角会出现一个方形的多彩按钮。

Code

import { IconArrowUp } from '@fibrous/semi-icons-react';
import { BackTop } from '@fibrous/semi-ui-react';

export default function BackTopDemo() {
    return (
        <div>
            <span>向下滚动，右下角会出现一个方形的多彩按钮。</span>
            <BackTop aria-label="回到顶部" icon={<IconArrowUp />} shape="square" size="large" colorful style={{ bottom: 100 }} />
        </div>
    );
}

API Reference

Props

Property	Description	Type	Default
aria-label	Accessible name of the button. Without it and without children, the locale's 'Back to top' is used.	`string`	-
badge	Badge props, same as FloatButton.	`BadgeProps`	-
children	Static content of the button, shown in place of `icon` when passed. It must not contain interactive elements such as links, buttons or inputs; a warning is logged in development when it does.	`React.ReactNode`	-
className	Class name, merged with the component's own class name on the `<button>`.	`string`	-
colorful	Colorful button, same as FloatButton; `false` when unset.	`boolean`	-
duration	Milliseconds the scroll to the top takes. The click event is throttled by this interval.	`number`	`450`
icon	Button icon, passed as an element. Defaults to IconBackTop.	`React.ReactNode`	-
onClick	Called on click with the native click event. Throttled by duration, and called once the scroll has started.	`Type`	-
ref	Points to the `<button>`, which exists only while the button is visible.	`Type`	-
shape	Shape: `round` or `square`. Falls back to the FloatButton default `round` when unset.	`'square' \| 'round'`	-
size	Size: `default`, `small` or `large`. Falls back to the FloatButton default `default` when unset.	`'small' \| 'default' \| 'large'`	-
style	Inline style of the button, used to override its default position and other styles.	`React.CSSProperties`	-
target	Function returning the scrolled element, the window when unset. Returning null means the node is not available yet. Called once after mount, when the ref of a parent container is already readable, and afterwards only when the function itself changes. A stable function that returns the element only after mount needs BackTop remounted.	`Type`	-
visibilityHeight	Scroll distance after which the BackTop appears.	`number`	`400`

Other native props (such as data-* and aria-*) are spread through ...rest into FloatButton and land on the <button>.

Accessibility

ARIA

BackTop renders a single native <button type="button">, which screen readers announce as a button
The accessible name comes from aria-label; without it, it comes from the button content when content is passed, and otherwise from the locale's default name ('Back to top' in English)
children (the default slot in Vue) is static content of the button and becomes part of its name; the button must not contain interactive elements

Keyboard and focus

Once visible, the button is reached with Tab and Shift + Tab, and Enter or Space scrolls to the top
A focus outline is shown on keyboard focus

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$spacing-backtop-right	100px	返回顶部距离右侧距离
$spacing-backtop-bottom	50px	返回顶部距离底侧距离