Pagination New Alpha Light DOM & Tailwind

Usage

Pagination is the navigation root for moving through a paginated collection. It is composition-first: it owns no page state, renders no controls, and emits no events. Your app owns the page state, URLs, cursors and any data fetching; Nord supplies the semantic/layout primitives, the styling, and the paginate() math utility for building the page window.

Import the parts you need — each import registers its custom element:

import "@nordhealth/components/lib/Pagination"
import "@nordhealth/components/lib/PaginationContent"
import "@nordhealth/components/lib/PaginationItem"
import "@nordhealth/components/lib/PaginationLink"
import "@nordhealth/components/lib/PaginationPrevious"
import "@nordhealth/components/lib/PaginationNext"
import "@nordhealth/components/lib/PaginationEllipsis"

Compose the primitives inside the root, bringing your own interactive element — an <a> (e.g. a framework <Link> / <NuxtLink> for crawlable, SSR-friendly links) or a nord-button. You own each link's href, navigation and disabled state. The root sets role="navigation" and a default accessible label for you, so there's no separate <nav> to add.

Pagination is navigation-only. A typical data-table footer pairs the numbered pages with a results summary and a page-size selector — but those are your app's own plain elements (a text node and a nord-select), not pagination sub-components:

The primitives are:

• nord-pagination — the navigation root (a navigation landmark).
• nord-pagination-content — the list row that lays its items out horizontally.
• nord-pagination-item — a single slot in the row.
• nord-pagination-link — a page link; set current on the active page and it mirrors aria-current="page" onto your link.
• nord-pagination-previous / nord-pagination-next — the previous/next controls.
• nord-pagination-ellipsis — the collapsed-pages marker (…) with a hidden label.

Pagination renders in the light DOM, so you can style it directly with your own CSS or Tailwind utilities.

Examples

Simple

Plain numbered pages with no previous/next controls. Mark the active page with current.

Numbered pages

The classic numbered pager: previous, the page-window numbers around the current page, an ellipsis for the collapsed gap, and next. Use the paginate() utility to compute which numbers (and ellipses) to render around the current page.

Icons only

A "Rows per page" selector on one end and icon-only previous/next on the other, justified to the row's two ends. For an icon-only nord-button, put a nord-visually-hidden label inside the button — never an aria-label on the host.

Cursor pagination

For collections with unknown totals (e.g. relay-style cursors), compose previous/next only. Your app enables or disables each control from its API response's page info.

Right-to-left

The primitives use logical properties, so in a right-to-left document they mirror automatically — set dir="rtl" on a wrapping element. Provide localized previous/next labels and page numbers yourself.

Building the page window

For numbered pages with known totals, the paginate() utility returns the sequence of page numbers (and ellipsis markers) to render, keeping the window centred on the current page and collapsing long gaps into a single ellipsis:

import { paginate } from "@nordhealth/components"

// paginate(currentPage, pageCount, pagesShown = 7)
paginate(6, 50) // → [1, "…", 4, 5, 6, 7, 8, "…", 50]

Map the tokens to nord-pagination-link (for numbers) and nord-pagination-ellipsis (for the "…" marker) yourself, setting current on the token that equals the current page.

Framework integration

Pagination is composition-first, so integration is just rendering your own links from your own state. Bind clicks/navigation with whatever your framework provides — there is no custom event to listen for.

Next.js

Use next/link for the page links so navigation is client-side and crawlable. Compute the window with paginate() and read the current page from the URL.

import Link from "next/link"
import { paginate } from "@nordhealth/components"

export function Results({ page, pageCount }: { page: number; pageCount: number }) {
  return (
    <nord-pagination>
      <nord-pagination-content>
        {paginate(page, pageCount).map((token, i) =>
          token === "…" ? (
            <nord-pagination-item key={`gap-${i}`}>
              <nord-pagination-ellipsis />
            </nord-pagination-item>
          ) : (
            <nord-pagination-item key={token}>
              {/* `current` mirrors aria-current onto the <a> */}
              <nord-pagination-link current={token === page}>
                <Link href={`?page=${token}`}>{token}</Link>
              </nord-pagination-link>
            </nord-pagination-item>
          )
        )}
      </nord-pagination-content>
    </nord-pagination>
  )
}

Nuxt.js

Use <NuxtLink> for the page links and read the current page from the route.

<script setup lang="ts">
import { paginate } from "@nordhealth/components"

const props = defineProps<{ pageCount: number }>()
const route = useRoute()
const page = computed(() => Number(route.query.page ?? 1))
const tokens = computed(() => paginate(page.value, props.pageCount))
</script>

<template>
  <nord-pagination>
    <nord-pagination-content>
      <nord-pagination-item v-for="(token, i) in tokens" :key="i">
        <nord-pagination-ellipsis v-if="token === '…'" />
        <nord-pagination-link v-else :current="token === page">
          <NuxtLink :to="{ query: { ...route.query, page: token } }">{{ token }}</NuxtLink>
        </nord-pagination-link>
      </nord-pagination-item>
    </nord-pagination-content>
  </nord-pagination>
</template>

TanStack Table

TanStack owns the table's 0-based pageIndex; use paginate() only for the visible page window and map page ↔ pageIndex at the boundary.

import { paginate } from "@nordhealth/components"

const pageCount = table.getPageCount()
const page = table.getState().pagination.pageIndex + 1 // 1-based for paginate()

const tokens = paginate(page, pageCount)
// Render each numeric token as a nord-pagination-link whose click calls:
//   table.setPageIndex(token - 1)
// and the ellipsis token as a nord-pagination-ellipsis.

Accessibility

• The root is a navigation landmark with a default accessible label, so screen-reader users can jump to it. Override it with your own aria-label or aria-labelledby when a page has more than one pager.
• Mark the active page by setting current on its nord-pagination-link; it mirrors aria-current="page" onto your link.
• For icon-only previous/next controls, put a nord-visually-hidden label inside the nord-button (never an aria-label on the host). Disable a control when there is nowhere to go.
• The ellipsis glyph is hidden from assistive tech and carries a visually-hidden label; localise it with the label property.