R
导航ScrollProgress阅读进度squircleMotion

滚动进度

跟随阅读位置的进度胶囊。点击后会展开成 squircle 菜单，直接跳到任意章节。

一、滚动进度

底部的胶囊会实时反映你的阅读位置。它固定在视口下方，滚动条走到哪里，胶囊就填到哪里。

当页面足够长时，进度本身就成了导航的一部分，而不是一个额外要看的指示器。

二、展开成菜单

点击胶囊，它会展开成一个 squircle 菜单，把 sections 里的章节列出来。

选中任意一项即可平滑跳转，弹簧动画让这个展开动作有明确的重量感。

三、无障碍与 reduced motion

组件遵循 prefers-reduced-motion：当系统要求减少动效时，位移被移除，只保留必要的状态变化。

在上面的区域里滚动，然后点击底部的胶囊。

上面的组件正在页面上实时运行，可以直接交互。

安装

在项目根目录执行下面的命令，组件源码会写入 @/components/ui/scroll-progress.tsx。

npx shadcn@latest add swamimalode07/rare-ui/scroll-progress

用法

组件默认导出（或具名导出）即可直接使用，不需要额外的 Provider。

scroll-progress.tsx
import ScrollProgress from "@/components/ui/scroll-progress"


const sections = [
  { id: "intro", label: "介绍" },
  { id: "install", label: "安装" },
  { id: "props", label: "属性" },
]


export function Demo() {
  return <ScrollProgress sections={sections} offset={120} />
}

属性

下表列出了该组件公开的主要属性，所有未列出的原生属性都会透传到根元素。

属性类型默认值说明
sections{ id: string; label: string }[]—可跳转的章节列表。
containerRefRefObject<HTMLElement | null>—滚动容器；默认跟随页面。
offsetnumber120判定激活章节的偏移量。