用法

import { Pagination } from '@heroui/react';

组件结构

导入 Pagination 组件后，可通过点号访问各个子部分。

import { Pagination } from '@heroui/react';

export default () => (
  <Pagination>
    <Pagination.Summary>Showing 1-10 of 100 results</Pagination.Summary>
    <Pagination.Content>
      <Pagination.Item>
        <Pagination.Previous>
          <Pagination.PreviousIcon />
          <span>Previous</span>
        </Pagination.Previous>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Link isActive>1</Pagination.Link>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Ellipsis />
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Link>10</Pagination.Link>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Next>
          <span>Next</span>
          <Pagination.NextIcon />
        </Pagination.Next>
      </Pagination.Item>
    </Pagination.Content>
  </Pagination>
);

示例

尺寸

小

中

大

禁用

受控组件

带省略号

带摘要

自定义图标

可通过向 PreviousIcon 与 NextIcon 传入自定义子元素来替换默认 chevron 图标。

自定义样式

Tailwind CSS

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {
  .pagination {
    @apply gap-8;
  }

  .pagination__link {
    @apply rounded-md;
  }

  .pagination__summary {
    @apply text-xs font-semibold;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Pagination 使用以下 CSS 类（查看源码样式）：

基础与布局类

.pagination - 根导航容器（flex 布局）
.pagination__summary - 左侧信息文本容器
.pagination__content - 分页项容器
.pagination__item - 单个分页项包裹层
.pagination__link - 页码按钮（ghost 按钮样式）
.pagination__link--nav - 导航按钮修饰符（Previous/Next）
.pagination__ellipsis - 省略号指示器

尺寸类

.pagination--sm - 小尺寸变体
.pagination--md - 中尺寸变体（默认）
.pagination--lg - 大尺寸变体

交互状态

组件同时支持 CSS 伪类与 data 属性，便于灵活定制：

Active page：[data-active="true"] 或 [aria-current="page"]
Hover：:hover 或 [data-hovered="true"]
Focus：:focus-visible 或 [data-focus-visible="true"]
Disabled：:disabled 或 [aria-disabled="true"]
Pressed：:active 或 [data-pressed="true"]

API 参考

Pagination

Prop	类型	默认值	描述
`size`	`"sm" \| "md" \| "lg"`	`"md"`	分页控件的尺寸
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	分页部件（Summary、Content 等）

Pagination.Summary

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	摘要内容（例如 "Showing 1-10 of 120"）

Pagination.Content

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	分页项

Pagination.Item

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	项内容（Link、Previous、Next 或 Ellipsis）

Pagination.Link

Prop	类型	默认值	描述
`isActive`	`boolean`	`false`	是否为当前页
`isDisabled`	`boolean`	`false`	是否禁用链接
`onPress`	`(e: PressEvent) => void`	-	按下事件处理函数（来自 React Aria）
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	页码内容

Pagination.Previous / Pagination.Next

Prop	类型	默认值	描述
`isDisabled`	`boolean`	`false`	是否禁用按钮
`onPress`	`(e: PressEvent) => void`	-	按下事件处理函数（来自 React Aria）
`className`	`string`	-	额外的 CSS 类
`children`	`ReactNode`	-	按钮内容（可与 PreviousIcon/NextIcon 组合）