Pagination

여러 페이지로 나뉜 목록에서 페이지를 이동하는 컨트롤입니다. 각 번호는 Button으로 렌더링됩니다.

import { Pagination } from 'neba';

<Pagination count={24} page={page} onPageChange={setPage} showEdges />;

Props

Prop	타입	기본값	설명
locale	string	—	BCP 47 태그. nav 이름, 페이지 버튼, 화살표, 현재 위치 문장을 모두 이 언어로 씁니다
variant공통	'solid' | 'outline' | 'text'	'text'	쉬고 있는 페이지 버튼의 무게. 기본값은 text이며, 현재 페이지는 언제나 solid로 그려집니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	버튼의 높이와 타입 스케일. 실제로 Button이므로 옆에 놓인 같은 size의 버튼과 줄이 맞습니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'compact'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
count *	number	—	전체 페이지 수. 둘보다 적으면 아무것도 그리지 않습니다. 할 일이 없다고 광고하는 컨트롤은 컨트롤이 아닙니다
page	number	—	현재 페이지(1부터). controlled
defaultPage	number	1	처음 페이지
onPageChange	(page: number) => void	—	페이지가 바뀔 때
siblingCount	number	1	현재 페이지 양옆에 언제나 보이는 페이지 수
boundaryCount	number	1	양 끝에 언제나 보이는 페이지 수. 0이면 첫 페이지와 마지막 페이지가 빠지고 창만 남습니다
showEdges	boolean	false	맨 앞 / 맨 뒤로 건너뛰는 버튼
showArrows	boolean	true	이전 / 다음 버튼
disabled	boolean	false	사용 불가. 줄 전체가 반응하지 않습니다
getPageHref	(page: number) => string	—	페이지의 주소. 넘기면 번호가 실제 링크가 되어 크롤러가 따라갈 수 있고, 좌우 화살표에 rel="prev" / rel="next"가 붙습니다
label	string	—	nav 랜드마크의 접근성 이름
pageLabel	(page: number) => string	—	페이지 버튼의 접근성 이름. 기본값은 locale의 표현
previousLabel	string	—	이전 버튼의 접근성 이름
nextLabel	string	—	다음 버튼의 접근성 이름
firstLabel	string	—	맨 앞 버튼의 접근성 이름
lastLabel	string	—	맨 뒤 버튼의 접근성 이름

count가 1이면 아무것도 렌더링하지 않습니다.

예시

variant

variant는 페이지 버튼이 선택되지 않은 상태의 모습입니다. 현재 페이지는 variant와 무관하게 항상 채워집니다.

기본값은 Button과 달리 text입니다. 한 줄에 채워진 버튼이 여러 개 있으면 어느 것이 현재 페이지인지 구분되지 않습니다.

import { Pagination, Typography } from 'neba';

/**
 * `variant` is how the pages look *at rest*. The current page is always filled,
 * whatever the row's resting variant is — it is the one thing here that has to
 * be legible without being read.
 */
export default function PaginationVariants() {
  return (
    <div className="flex flex-col gap-5">
      {(['text', 'outline', 'solid'] as const).map((variant) => (
        <div key={variant} className="flex flex-col gap-1">
          <Typography level="caption">variant="{variant}"</Typography>
          <Pagination count={9} defaultPage={4} variant={variant} />
        </div>
      ))}
    </div>
  );
}

siblingCount · boundaryCount · showEdges · showArrows

siblingCount는 현재 페이지 양옆에 보일 번호 개수, boundaryCount는 처음과 끝에 항상 보일 번호 개수입니다. showEdges는 첫·마지막 페이지로 가는 버튼을, showArrows는 이전·다음 버튼을 표시합니다.

줄의 칸 개수는 페이지가 바뀌어도 일정하게 유지됩니다. 창이 끝에 가까워지면 잘리는 대신 그쪽으로 미끄러지므로, 페이지를 넘길 때 버튼들이 포인터 아래에서 재배치되지 않습니다. 생략될 페이지가 하나뿐일 때는 줄임표 대신 그 번호를 그립니다.

import { Pagination, Typography } from 'neba';

/**
 * The window slides toward whichever end it is near rather than being clipped by
 * it, so the row keeps the same number of slots on every page. Which slots are
 * pages and which are ellipses changes; how many there are does not — otherwise
 * stepping from page 1 to page 2 would relayout the row and move every button
 * out from under the pointer that just pressed one.
 */
export default function PaginationRange() {
  return (
    <div className="flex flex-col gap-5">
      {[1, 2, 10, 19, 20].map((page) => (
        <div key={page} className="flex flex-col gap-1">
          <Typography level="caption">page={page}</Typography>
          <Pagination count={20} page={page} showArrows={false} />
        </div>
      ))}

      <div className="flex flex-col gap-1">
        <Typography level="caption">
          siblingCount={2} · boundaryCount={2}
        </Typography>
        <Pagination count={20} page={10} siblingCount={2} boundaryCount={2} showArrows={false} />
      </div>
    </div>
  );
}

size

import { Pagination } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function PaginationSizes() {
  return (
    <div className="flex flex-col gap-4">
      {SIZES.map((size) => (
        <Pagination key={size} size={size} count={9} defaultPage={4} />
      ))}
    </div>
  );
}

getPageHref

페이지의 주소를 돌려주면 줄의 번호들이 실제 <a href>가 됩니다. 크롤러는 버튼을 누르지 못하므로, 이것 없이는 목록의 2페이지 이후가 검색 엔진에 존재하지 않습니다. 새 탭으로 열기, 주소 복사, 누르기 전에 목적지 확인 같은 브라우저의 기본 동작도 함께 돌아옵니다. 좌우 화살표에는 rel="prev"와 rel="next"가 붙습니다.

onPageChange를 함께 넘기면 이동이 취소되고 핸들러가 대신 답합니다. client-side router가 이미 가진 페이지를 유지하는 방식입니다. 핸들러가 없으면 링크가 하던 일을 그대로 합니다. 수정 키를 누른 채 클릭한 경우는 언제나 브라우저에 맡깁니다.

읽고 있는 페이지와 줄 끝에 닿은 화살표는 <button>으로 남습니다. <a>는 disabled가 될 수 없어서, 링크로 두면 키보드가 계속 도달하고 크롤러도 따라가기 때문입니다.

import { useState } from 'react';
import { Pagination, Typography } from 'neba';

/**
 * The same row twice. Above, `getPageHref` alone: every number is an `<a href>`
 * and pressing one is a navigation, which is what a crawler follows and what a
 * middle-click opens in a new tab. Below, the same links with a handler behind
 * them — the press is cancelled and the page stays, which is the shape a
 * client-side router wants.
 */
export default function PaginationLinks() {
  const [page, setPage] = useState(3);

  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-col gap-1">
        <Typography level="caption">getPageHref</Typography>
        <Pagination count={12} page={3} getPageHref={(value) => `/posts?page=${value}`} />
      </div>

      <div className="flex flex-col gap-1">
        <Typography level="caption">getPageHref + onPageChange</Typography>
        <Pagination
          count={12}
          page={page}
          getPageHref={(value) => `/posts?page=${value}`}
          onPageChange={setPage}
        />
      </div>
    </div>
  );
}

접근성

• <nav>가 <ul>을 감싸는 구조로 렌더링되고, 현재 페이지에 aria-current="page"가 붙습니다.
• 줄임표는 버튼이 아니라 문장 부호이므로 비활성 버튼으로 렌더링되지 않습니다.
• getPageHref를 넘기면 번호가 링크가 되므로 스크린리더의 링크 목록에 올라가고, 키보드 사용자가 목적지를 미리 확인할 수 있습니다.
• accessible name은 label · pageLabel · previousLabel · nextLabel · firstLabel · lastLabel로 모두 지정할 수 있습니다. 한 화면에 Pagination이 여러 개라면 label로 각각이 무엇의 페이지인지 밝혀 주세요.
• nav 이름, 페이지 버튼, 화살표, 현재 위치를 읽는 문장까지 모두 locale이 정합니다. 어느 것이든 각자의 prop으로 직접 쓸 수 있습니다.