Pagination

Overview

The Pagination component provides a flexible, composable Bulma pagination navigation for your Bulma React UI.

It supports size, alignment, rounded corners, disabled states, and both controlled and uncontrolled usage. Use the provided subcomponents to build complex paginations: previous/next buttons, page links, ellipsis, and custom content. (The root color prop is deprecated: Bulma ships no pagination color CSS, so it has never had a visual effect.)

info

Use Pagination for navigating lists of results, pages, or any content split across screens.

---

Import

import { Pagination } from '@allxsmith/bestax-bulma';

---

Usage

Basic Pagination

This example demonstrates a basic pagination navigation using Pagination, Pagination.List, and Pagination.Link subcomponents. The active prop highlights the current page, while previous/next arrows and an ellipsis provide navigation for larger sets. Adjust the structure to match your data set or navigation needs.

<Pagination>
  <Pagination.List>
    <Pagination.Link>&laquo;</Pagination.Link>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
    <Pagination.Link>&raquo;</Pagination.Link>
  </Pagination.List>
</Pagination>

---

Sizes

Showcases the use of the size prop to render paginations in different sizes. Set size="small", size="medium", or size="large" to match the pagination to your UI scale. Each instance below demonstrates a different size, with the active prop indicating the current page.

<>
  <Pagination size="small" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination size="medium" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination size="large">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
</>

---

Alignment

Demonstrates the align prop to control the pagination alignment. Use align="centered" to center the pagination, or align="right" to align it to the right. This affects the entire pagination component, including the list of links and any additional content.

<>
  <Pagination align="centered" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination align="right">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
</>

---

Rounded

This example demonstrates the rounded prop, which renders the pagination with rounded corners for a softer, modern look. Use rounded to visually distinguish pagination controls or match your app's design language.

<Pagination rounded>
  <Pagination.List>
    <Pagination.Link>1</Pagination.Link>
    <Pagination.Link active>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
  </Pagination.List>
</Pagination>

---

With Disabled

This example shows how to use the disabled prop on Pagination.Link to indicate unavailable navigation options. Here, the first link is disabled, preventing user interaction. Use disabled for links that should not be clickable, such as when on the first or last page.

<Pagination>
  <Pagination.List>
    <Pagination.Link disabled>&laquo;</Pagination.Link>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
    <Pagination.Link>&raquo;</Pagination.Link>
  </Pagination.List>
</Pagination>

---

Controlled Pagination

This example demonstrates a controlled pagination pattern using the page state and the onClick handler on each Pagination.Link. The current page is tracked in state, and clicking a link updates the page. Use this approach for paginations where you need to manage the current page in your app logic.

function example() {
  const [page, setPage] = useState(1);
  return (
    <>
      <Pagination>
        <Pagination.Previous
          disabled={page === 1}
          onClick={() => setPage(page - 1)}
        >
          Previous
        </Pagination.Previous>
        <Pagination.Next
          disabled={page === 5}
          onClick={() => setPage(page + 1)}
        >
          Next
        </Pagination.Next>
        <Pagination.List>
          {[1, 2, 3, 4, 5].map(i => (
            <Pagination.Link
              key={i}
              active={i === page}
              onClick={() => setPage(i)}
            >
              {i}
            </Pagination.Link>
          ))}
        </Pagination.List>
      </Pagination>
      <Paragraph mt="2">Current page: {page}</Paragraph>
    </>
  );
}

---

From a Page Count

Give Pagination a total and no children, and it renders the whole control itself: Previous, Next and a link for each page it shows, with an ellipsis where it skips a run of pages. current and onPageChange make it controlled; leave current out and it keeps the page itself. siblingCount sets how many pages show on each side of the current one, and boundaryCount how many always show at each end, and the row keeps its length as the page moves. Pass getPageHref to make each page a real link, for URLs like ?page=3. With children, Pagination renders those instead, as in the examples above.

function example() {
  const [page, setPage] = useState(10);
  return (
    <>
      <Pagination total={20} current={page} onPageChange={setPage} />
      <Paragraph mt="2">Current page: {page}</Paragraph>
    </>
  );
}

---

Previous/Next with Pagination List

This example combines the Pagination.Previous and Pagination.Next subcomponents with a Pagination.List for a more advanced navigation pattern. Use Previous and Next for clear navigation controls, and combine with Pagination.Link and Pagination.Ellipsis for complex paginations.

<Pagination align="centered">
  <Pagination.Previous>Previous</Pagination.Previous>
  <Pagination.Next>Next page</Pagination.Next>
  <Pagination.List>
    <Pagination.Link aria-label="Goto page 1">1</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link aria-label="Goto page 45">45</Pagination.Link>
    <Pagination.Link active aria-label="Page 46">
      46
    </Pagination.Link>
    <Pagination.Link aria-label="Goto page 47">47</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link aria-label="Goto page 86">86</Pagination.Link>
  </Pagination.List>
</Pagination>

---

Compound (dot-notation) usage

Every subcomponent is exported by name (PaginationLink, PaginationList, …) and attached to Pagination as a static, so a full pagination can be composed from the single Pagination import.

<Pagination>
  <Pagination.Previous>Previous</Pagination.Previous>
  <Pagination.Next>Next page</Pagination.Next>
  <Pagination.List>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
  </Pagination.List>
</Pagination>

---

Accessibility

• The root Pagination renders as a semantic <nav role="navigation" aria-label="pagination">.
• Use aria-label on page links for better screen reader support.
• Disabled and active states are handled with ARIA attributes and classes.
• Rendered from total, each page's link is named for its page ("Page 3"; pass getPageLabel for your own words), and the current page's link carries aria-current="page". Without getPageHref the links have no href, so they carry role="button" and choose a page with Enter or Space.

note

Pagination links are rendered as <a> elements for accessibility and keyboard navigation.

---

Related Components

• Helper Props: All Bulma utility helpers can be used.
• Button: For custom page controls if needed.

---

Additional Resources

• Bulma Pagination Documentation
• Storybook: Pagination Stories

Pro Tip

You can use all Bulma helper props with <Pagination /> and its subcomponents for utility-based styling.

---

Props

Prop	Type	Default	Description
color	'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white'	—	Deprecated. No .pagination.is-<color> CSS exists; the prop renders unstyled and will be removed in the next major version. Color modifier for the pagination (renders is-<color>). Bulma ships no pagination color CSS, so this prop has never had a visual effect for any value. Passing it logs a console warning in development. Use textColor / bgColor instead.
textColor	Bulma color | 'inherit' | 'current'	—	Text color helper.
bgColor	Bulma color | 'inherit' | 'current'	—	Background color helper.
size	'small' | 'medium' | 'large'	—	Size modifier for the pagination.
align	'centered' | 'right'	—	Alignment for the pagination.
rounded	boolean	false	Renders pagination with rounded corners.
total	number	—	The number of pages. Given total and no children, Pagination renders the whole control itself: Previous, Next and a link for each page it shows, with an ellipsis where it skips some. Given children, it renders those as they are, and total and the other page props do nothing.
current	number	—	The page shown as current, counting from 1, when rendering from total. Leave it out and Pagination keeps the page itself, starting at 1.
onPageChange	(page: number) => void	—	Called with the page chosen, when rendering from total. Choosing the page already current doesn't call it.
siblingCount	number	1	How many pages to show on each side of the current one, when rendering from total.
boundaryCount	number	1	How many pages to always show at the start and at the end, when rendering from total.
previousLabel	React.ReactNode	'Previous'	The Previous link's content, when rendering from total.
nextLabel	React.ReactNode	'Next'	The Next link's content, when rendering from total.
disabled	boolean	false	Disables every link, when rendering from total.
getPageHref	(page: number) => string	—	The href for a page's link, when rendering from total, making each one a real link (page => '?page=' + page). A click then calls onPageChange and the browser follows the link too. Without it the links have no href, act as buttons, and Enter or Space chooses a page.
getPageLabel	(page: number) => string	—	The accessible name of a page's link, when rendering from total, since its content is only the number (page => 'Page ' + page by default).
className	string	—	Additional CSS classes.
children	React.ReactNode	—	Custom pagination content (usually subcomponents).
...	All standard HTML attributes and Bulma helper props	—	See Helper Props

Subcomponents:

• Pagination.Link: Page number or navigation link.
• Pagination.List: Container for page links and ellipsis.
• Pagination.Ellipsis: Ellipsis separator.
• Pagination.Previous: "Previous" navigation button.
• Pagination.Next: "Next" navigation button.

Pagination.Link

Prop	Type	Default	Description
className	string	—	Additional CSS classes.
color	'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger'	—	Bulma color modifier.
textColor	Bulma color | 'inherit' | 'current'	—	Text color.
bgColor	Bulma color | 'inherit' | 'current'	—	Background color.
active	boolean	false	Whether the link is for the current page.
disabled	boolean	false	Whether the link is disabled.
children	React.ReactNode	—	Link content.
...	All standard <a> attributes and Bulma helper props	—	See Helper Props

Pagination.List

Prop	Type	Default	Description
className	string	—	Additional CSS classes.
textColor	Bulma color | 'inherit' | 'current'	—	Text color for the list.
color	'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger'	—	Bulma color modifier for the list.
bgColor	Bulma color | 'inherit' | 'current'	—	Background color for the list.
children	React.ReactNode	—	List items.
...	All standard <ul> attributes and Bulma helper props	—	See Helper Props

Pagination.Previous

Prop	Type	Default	Description
className	string	—	Additional CSS classes.
disabled	boolean	false	Whether previous/next is disabled.
children	React.ReactNode	—	Button content.
...	All standard <a> attributes	—

Pagination.Next

Prop	Type	Default	Description
className	string	—	Additional CSS classes.
disabled	boolean	false	Whether previous/next is disabled.
children	React.ReactNode	—	Button content.
...	All standard <a> attributes	—

CSS & Sass Variables

Pagination registers these variables on its own .pagination element. Override them there (or via className) — a value set on an ancestor is only inherited, and loses to the component-level declaration. See Theme.

CSS Variable	Sass Variable	Default
--bulma-pagination-margin	$pagination-margin	-0.25rem
--bulma-pagination-min-width	$pagination-min-width	var(--bulma-control-height)
--bulma-pagination-item-h	$pagination-item-h	var(--bulma-scheme-h)
--bulma-pagination-item-s	$pagination-item-s	var(--bulma-scheme-s)
--bulma-pagination-item-l	$pagination-item-l	var(--bulma-scheme-main-l)
--bulma-pagination-item-background-l-delta	$pagination-item-background-l-delta	0%
--bulma-pagination-item-hover-background-l-delta	$pagination-item-hover-background-l-delta	var(--bulma-hover-background-l-delta)
--bulma-pagination-item-active-background-l-delta	$pagination-item-active-background-l-delta	var(--bulma-active-background-l-delta)
--bulma-pagination-item-border-style	$pagination-item-border-style	solid
--bulma-pagination-item-border-width	$pagination-item-border-width	var(--bulma-control-border-width)
--bulma-pagination-item-border-l	$pagination-item-border-l	var(--bulma-border-l)
--bulma-pagination-item-border-l-delta	$pagination-item-border-l-delta	0%
--bulma-pagination-item-hover-border-l-delta	$pagination-item-hover-border-l-delta	var(--bulma-hover-border-l-delta)
--bulma-pagination-item-active-border-l-delta	$pagination-item-active-border-l-delta	var(--bulma-active-border-l-delta)
--bulma-pagination-item-focus-border-l-delta	$pagination-item-focus-border-l-delta	var(--bulma-focus-border-l-delta)
--bulma-pagination-item-color-l	$pagination-item-color-l	var(--bulma-text-strong-l)
--bulma-pagination-item-font-size	$pagination-item-font-size	1em
--bulma-pagination-item-margin	$pagination-item-margin	0.25rem
--bulma-pagination-item-padding-left	$pagination-item-padding-left	0.5em
--bulma-pagination-item-padding-right	$pagination-item-padding-right	0.5em
--bulma-pagination-item-outer-shadow-h	$pagination-item-outer-shadow-h	0
--bulma-pagination-item-outer-shadow-s	$pagination-item-outer-shadow-s	0%
--bulma-pagination-item-outer-shadow-l	$pagination-item-outer-shadow-l	20%
--bulma-pagination-item-outer-shadow-a	$pagination-item-outer-shadow-a	0.05
--bulma-pagination-nav-padding-left	$pagination-nav-padding-left	0.75em
--bulma-pagination-nav-padding-right	$pagination-nav-padding-right	0.75em
--bulma-pagination-disabled-color	$pagination-disabled-color	var(--bulma-text-weak)
--bulma-pagination-disabled-background-color	$pagination-disabled-background-color	var(--bulma-border)
--bulma-pagination-disabled-border-color	$pagination-disabled-border-color	var(--bulma-border)
--bulma-pagination-current-color	$pagination-current-color	var(--bulma-link-invert)
--bulma-pagination-current-background-color	$pagination-current-background-color	var(--bulma-link)
--bulma-pagination-current-border-color	$pagination-current-border-color	var(--bulma-link)
--bulma-pagination-ellipsis-color	$pagination-ellipsis-color	var(--bulma-text-weak)
--bulma-pagination-shadow-inset	$pagination-shadow-inset	inset 0 0.0625em 0.125em hsla(var(--bulma-scheme-h), var(--bulma-scheme-s), var(--bulma-scheme-invert-l), 0.2)
--bulma-pagination-selected-item-h	$pagination-selected-item-h	var(--bulma-link-h)
--bulma-pagination-selected-item-s	$pagination-selected-item-s	var(--bulma-link-s)
--bulma-pagination-selected-item-l	$pagination-selected-item-l	var(--bulma-link-l)
--bulma-pagination-selected-item-background-l	$pagination-selected-item-background-l	var(--bulma-link-l)
--bulma-pagination-selected-item-border-l	$pagination-selected-item-border-l	var(--bulma-link-l)
--bulma-pagination-selected-item-color-l	$pagination-selected-item-color-l	var(--bulma-link-invert-l)