Pagination

Pagination is a navigational element that allows users to navigate between content or pages.

Usage

Pagination is used when you cannot fit the entire content on the screen. Pagination navigates through content but keeps the user on the same page. In some instances, users can choose how much content is displayed per page through a filter. This will ultimately increase or decrease the total number of pages.

Variants

Centered Pagination

Centered pagination displays the full pagination controls in the center of the container. This is useful when pagination is the primary focus.

<terra-pagination centered current="10" total="20"></terra-pagination>

import TerraPagination from '@nasa-terra/components/dist/react/pagination';

const App = () => (
    <TerraPagination centered current={10} total={20} />
);

Left-Aligned Pagination with Slot

Left-aligned pagination displays pagination controls on the left and provides a slot on the right for additional content (such as a rows per page dropdown).

<terra-pagination current="5" total="20">
    <terra-dropdown>
        <terra-button slot="trigger" caret>10 per page</terra-button>
        <terra-menu>
            <terra-menu-item value="10">10 per page</terra-menu-item>
            <terra-menu-item value="25">25 per page</terra-menu-item>
            <terra-menu-item value="50">50 per page</terra-menu-item>
        </terra-menu>
    </terra-dropdown>
</terra-pagination>

import TerraPagination from '@nasa-terra/components/dist/react/pagination';
import TerraDropdown from '@nasa-terra/components/dist/react/dropdown';
import TerraButton from '@nasa-terra/components/dist/react/button';
import TerraMenu from '@nasa-terra/components/dist/react/menu';
import TerraMenuItem from '@nasa-terra/components/dist/react/menu-item';

const App = () => (
    <TerraPagination current={5} total={20}>
        <TerraDropdown>
            <TerraButton slot="trigger" caret>10 per page</TerraButton>
            <TerraMenu>
                <TerraMenuItem value="10">10 per page</TerraMenuItem>
                <TerraMenuItem value="25">25 per page</TerraMenuItem>
                <TerraMenuItem value="50">50 per page</TerraMenuItem>
            </TerraMenu>
        </TerraDropdown>
    </TerraPagination>
);

Prev/Next Only

For mobile pagination where the number of pages doesn’t exceed 5 pages, a simplified pagination can be used without numbers.

<terra-pagination variant="simple" current="2" total="5"></terra-pagination>

import TerraPagination from '@nasa-terra/components/dist/react/pagination';

const App = () => (
    <TerraPagination variant="simple" current={2} total={5} />
);

Examples

First Page

<terra-pagination centered current="1" total="20"></terra-pagination>

Middle Page

<terra-pagination centered current="10" total="20"></terra-pagination>

Last Page

<terra-pagination centered current="20" total="20"></terra-pagination>

Many Pages (with Ellipsis)

When there are many pages, ellipsis are shown to indicate skipped pages.

<terra-pagination centered current="50" total="100"></terra-pagination>

Few Pages (No Ellipsis)

When there are 7 or fewer pages, all page numbers are shown.

<terra-pagination centered current="3" total="7"></terra-pagination>

Events

Listen for the terra-page-change event to handle page changes:

<terra-pagination id="pagination" centered current="5" total="20"></terra-pagination>
<script>
    const pagination = document.getElementById('pagination');
    pagination.addEventListener('terra-page-change', (e) => {
        console.log('Page changed to:', e.detail.page);
    });
</script>

import TerraPagination from '@nasa-terra/components/dist/react/pagination';

const App = () => {
    function handlePageChange(event) {
        console.log('Page changed to:', event.detail.page);
    }

    return (
        <TerraPagination
            centered
            current={5}
            total={20}
            onTerraPageChange={handlePageChange}
        />
    );
};

Dark Mode

Pagination automatically adapts to dark mode based on system preference.

Light Background

<div style="background-color: #f5f5f5; padding: 2rem;">
    <terra-pagination centered current="10" total="20"></terra-pagination>
</div>

Dark Background

<div style="background-color: #1a1a1a; padding: 2rem;">
    <terra-pagination centered current="10" total="20"></terra-pagination>
</div>

Customization

You can customize pagination appearance using CSS custom properties:

terra-pagination {
    --terra-pagination-button-color: var(--terra-color-carbon-90);
    --terra-pagination-button-background-color: var(--terra-color-spacesuit-white);
    --terra-pagination-button-border-color: var(--terra-color-carbon-20);
    --terra-pagination-button-color-current: var(--terra-color-spacesuit-white);
    --terra-pagination-button-background-color-current: var(--terra-color-nasa-blue);
}

Design Tokens

The following design tokens are available for customization:

• --terra-pagination-button-color: Text color of page buttons (default: --terra-color-carbon-90 in light mode, --terra-color-carbon-60 in dark mode)
• --terra-pagination-button-background-color: Background color of page buttons (default: --terra-color-spacesuit-white in light mode, --terra-color-carbon-10 in dark mode)
• --terra-pagination-button-border-color: Border color of page buttons (default: --terra-color-carbon-20)
• --terra-pagination-button-color-hover: Text color of page buttons on hover (default: --terra-color-carbon-90 in light mode, --terra-color-carbon-80 in dark mode)
• --terra-pagination-button-background-color-hover: Background color of page buttons on hover (default: --terra-color-carbon-5)
• --terra-pagination-button-border-color-hover: Border color of page buttons on hover (default: --terra-color-carbon-30)
• --terra-pagination-button-color-current: Text color of the current page button (default: --terra-color-spacesuit-white)
• --terra-pagination-button-background-color-current: Background color of the current page button (default: --terra-color-nasa-blue in light mode, --terra-color-nasa-blue-tint in dark mode)
• --terra-pagination-button-border-color-current: Border color of the current page button (default: --terra-color-nasa-blue in light mode, --terra-color-nasa-blue-tint in dark mode)

All tokens automatically adapt to dark mode when dark mode is active.

[component-metadata:terra-pagination]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/pagination/pagination.js"></script>

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/pagination/pagination.js';

import '@nasa-terra/components/dist/components/pagination/pagination.js';

import TerraPagination from '@nasa-terra/components/dist/react/pagination';

Slots

Learn more about using slots.

Properties

Learn more about attributes and properties.

Events

Learn more about events.

Custom Properties

Learn more about customizing CSS custom properties.

Parts

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

• <terra-icon>