> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/back-top.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# BackTop 回到顶部

快速返回页面或滚动容器顶部。

## 基本用法


向下滚动后，右下角显示返回按钮。 1

向下滚动后，右下角显示返回按钮。 2

向下滚动后，右下角显示返回按钮。 3

向下滚动后，右下角显示返回按钮。 4

向下滚动后，右下角显示返回按钮。 5

向下滚动后，右下角显示返回按钮。 6

向下滚动后，右下角显示返回按钮。 7

向下滚动后，右下角显示返回按钮。 8

向下滚动后，右下角显示返回按钮。 9

向下滚动后，右下角显示返回按钮。 10

向下滚动后，右下角显示返回按钮。 11

向下滚动后，右下角显示返回按钮。 12

向下滚动后，右下角显示返回按钮。 13

向下滚动后，右下角显示返回按钮。 14

向下滚动后，右下角显示返回按钮。 15

向下滚动后，右下角显示返回按钮。 16

向下滚动后，右下角显示返回按钮。 17

向下滚动后，右下角显示返回按钮。 18

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/back-top/basic.tsx"
import { BackTop, ScrollArea } from '@ifhover/leaf-ui';

import { useRef } from 'react';

export function BackTopBasic() {
  const root = useRef<HTMLDivElement>(null);
  return (
    <div style={{ position: 'relative' }}>
      <ScrollArea ref={root} height={200} aria-label="演示滚动区域">
        {Array.from({ length: 18 }, (_, i) => (
          <p key={String(i)} style={{ padding: '4px 16px' }}>
            向下滚动后，右下角显示返回按钮。 {i + 1}
          </p>
        ))}
      </ScrollArea>
      <BackTop
        target={() => root.current}
        visibilityHeight={100}
        style={{ position: 'absolute', right: 16, bottom: 16 }}
      />
    </div>
  );
}
```

展开代码

## 更多用法


滚动查看返回按钮。

返回顶部

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/back-top/advanced.tsx"
import { BackTop, ScrollArea } from '@ifhover/leaf-ui';

import { useRef } from 'react';

export function BackTopCustom() {
  const root = useRef<HTMLDivElement>(null);
  return (
    <div style={{ position: 'relative' }}>
      <ScrollArea ref={root} height={180} aria-label="自定义返回按钮">
        <div style={{ height: 620, padding: 16 }}>滚动查看返回按钮。</div>
      </ScrollArea>
      <BackTop
        target={() => root.current}
        visibilityHeight={80}
        behavior="auto"
        style={{ position: 'absolute', right: 16, bottom: 16 }}
      >
        返回顶部
      </BackTop>
    </div>
  );
}
```

展开代码

## 使用说明

默认监听窗口滚动；target 可返回指定滚动容器。超过 visibilityHeight 后显示按钮，点击后返回顶部；尊重系统减少动画的偏好。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { BackTopProps } from '@ifhover/leaf-ui';
```

## BackTopProps API

| 属性                 | 类型                                    | 默认值        | 说明          |
| ------------------ | ------------------------------------- | ---------- | ----------- |
| `target`           | `() => HTMLElement \| Window \| null` | —          | 滚动目标或链接打开方式 |
| `visibilityHeight` | `number`                              | `400`      | 超过此滚动距离后显示  |
| `behavior`         | `ScrollBehavior`                      | `'smooth'` | 返回顶部的滚动方式   |