跳到正文
目录与搜索
⌘K

原语 / Animate UI

Scroll Progress · Animate UI

跟随页面或容器滚动位置的进度条。

安装

自有原语直接来自 @animate-ui/react,不依赖 Radix UI、Base UI 或 React Aria;装上包即可使用。

终端
bun add @animate-ui/react motion

用法

直接从 @animate-ui/react 的对应子路径引入,下面就是完整示例;样式由你的类名决定。

scroll-progress.tsx
import {
  ScrollProgress,
  ScrollProgressContainer,
  ScrollProgressProvider,
} from '@animate-ui/react/primitives/scroll-progress';

// A scrollable container.
export function Article() {
  return (
    <ScrollProgressProvider>
      <ScrollProgress className="h-1 bg-foreground" />
      <ScrollProgressContainer className="h-96 overflow-y-auto">
        …
      </ScrollProgressContainer>
    </ScrollProgressProvider>
  );
}

// The whole page.
export function PageProgress() {
  return (
    <ScrollProgressProvider global>
      <ScrollProgress className="fixed inset-x-0 top-0 h-1 bg-foreground" />
    </ScrollProgressProvider>
  );
}

动效

  • 进度以 stiffness 250 / damping 40 的弹簧追随滚动位置,不过冲,滚轮一格一格时也是滑过去而不是跳过去。
  • 减少动效下直接同步滚动位置。

所有时长都会乘以 AnimateUIProvider 的 tempo,并遵守系统的减少动效设置。

API

动效相关的 transition 与 exitTransition 是 Animate UI 唯一新增的属性;其余 props 见上表。

属性类型默认值
globalbooleanfalse
direction'vertical' | 'horizontal''vertical'
transitionSpringOptions{ stiffness: 250, damping: 40, bounce: 0 }
childrenReact.ReactNode—
asChildbooleanfalse
mode'width' | 'height' | 'scaleX' | 'scaleY''width'
…propsHTMLMotionProps<'div'>—
asChildbooleanfalse
…propsHTMLMotionProps<'div'>—

未列出的属性与上游 API 完全一致,可在 官方文档 查阅。

内容对应官方文档 2026-10-18 版本。