Pagination

Guidelines
React API Reference
Blazor API Reference

Pagination components help users navigate through large datasets by breaking content into manageable pages, providing clear navigation controls and context about their current position.

Guidance

Aspect	Best Practice
Usage	Use pagination for large datasets that would negatively impact performance or user experience if loaded all at once.
Content	Display clear page numbers, provide previous/next navigation, and show total context when helpful.
Behavior	Ensure smooth transitions between pages, maintain user context, and provide immediate feedback for navigation actions.
States	Clearly indicate current page, disabled states for boundary pages, and loading states during page transitions.
Feedback	Use visual indicators for active page, hover states for interactive elements, and clear labels for accessibility.
Examples	Search results, data tables, product listings, article archives, or any large dataset requiring navigation.

Best Practices

Logical Page Sizes: Choose appropriate page sizes that balance performance with user convenience.
Clear Navigation: Provide obvious previous/next controls and numbered page links when space allows.
Current Page Indication: Make the current page clearly distinguishable from other page numbers.
Responsive Design: Adapt pagination controls appropriately for different screen sizes.
Performance Optimization: Implement efficient data loading and caching strategies.
Accessible Controls: Ensure all pagination controls are keyboard accessible with appropriate ARIA labels.

Do’s and Don’ts

Do

Provide clear visual indication of the current page.
Include previous/next navigation for easy sequential browsing.
Show page size options when users might want different views.
Use consistent page sizes throughout the application.

Don't

Use pagination for small datasets that fit comfortably on one page.
Hide the total number of pages when it would be helpful context.
Make page numbers too small or difficult to interact with.
Forget to handle edge cases (first/last page states).

Additional Guidance

Psychological Impact:
- Sense of Progress: Pagination gives users a sense of progress and control over large datasets.
- Reduced Overwhelm: Breaking content into pages prevents cognitive overload from too much information.
- Manageable Navigation: Users can easily jump to specific sections or browse sequentially.

Import

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious
} from '@strongtie/design-system/pagination';

Usage

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink isActive>1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext />
    </PaginationItem>
  </PaginationContent>
</Pagination>

`<Pagination>` Props

role

string

default:"navigation"

The ARIA role for the pagination navigation.

`<PaginationLink>` Props

isActive

boolean

default:"false"

If true, the link represents the current active page.

Usage Examples

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink isActive>1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>3</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Styling Classes

The following CSS classes are applied by the Pagination components:

pagination – Root navigation container with appropriate ARIA attributes
pagination-content – Unordered list container for pagination items
pagination-item – Individual list item wrapper for each pagination element
pagination-link – Button element for page numbers and navigation
pagination-link.active – Active/current page styling
pagination-previous – Previous page navigation button
pagination-next – Next page navigation button
pagination-ellipsis – Ellipsis indicator for truncated page ranges
pagination-icon – Icon styling for navigation arrows and ellipsis

For more examples, visit the Storybook.

Example

<StudsPagination
    PageSize="10"
    Count="100"
    CurrentPage="0"
    PageChanged="@OnPageChanged"
    PageSizeOptions="@(new int[] { 10, 25, 50, 100 })"
/>

@code {
    void OnPageChanged(PagerEventArgs args)
    {
        // Handle page change
        Console.WriteLine($"Page changed to: {args.NewPageIndex}");
    }
}

`<StudsPagination>` Parameters

FirstPageTitle

string

default:"First page"

Gets or sets the pager’s first page button’s title attribute.

FirstPageAriaLabel

string

default:"Go to first page."

Gets or sets the pager’s first page button’s aria-label attribute.

PrevPageLabel

string

Gets or sets the pager’s optional previous page button’s label text.

PrevPageTitle

string

default:"Previous page"

Gets or sets the pager’s previous page button’s title attribute.

PrevPageAriaLabel

string

default:"Go to previous page."

Gets or sets the pager’s previous page button’s aria-label attribute.

LastPageTitle

string

default:"Last page"

Gets or sets the pager’s last page button’s title attribute.

LastPageAriaLabel

string

default:"Go to last page."

Gets or sets the pager’s last page button’s aria-label attribute.

NextPageLabel

string

Gets or sets the pager’s optional next page button’s label text.

NextPageTitle

string

default:"Next page"

Gets or sets the pager’s next page button’s title attribute.

NextPageAriaLabel

string

default:"Go to next page."

Gets or sets the pager’s next page button’s aria-label attribute.

PageTitleFormat

string

default:"Page {0}"

Gets or sets the pager’s numeric page number buttons’ title attributes.

PageAriaLabelFormat

string

default:"Go to page {0}."

Gets or sets the pager’s numeric page number buttons’ aria-label attributes.

PageSize

int

default:"10"

Gets or sets the page size (number of items per page).

PageSizeChanged

EventCallback<int>

Gets or sets the page size changed callback.

PageSizeOptions

IEnumerable<int>

Gets or sets the available page size options for the dropdown.

PageSizeText

string

default:"items per page"

Gets or sets the page size description text.

PageNumbersCount

int

default:"5"

Gets or sets the maximum number of page number buttons to display.

Count

int

Gets or sets the total number of items across all pages.

CurrentPage

int

Gets or sets the current page index (0-based).

AlwaysVisible

bool

default:"false"

Gets or sets a value indicating whether pager is visible even when there’s not enough data for paging.

PageChanged

EventCallback<PagerEventArgs>

Gets or sets the callback invoked when the current page changes.

SiblingCount

int

default:"1"

Gets or sets the number of sibling pages to show around the current page.

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

Usage Examples

<StudsPagination
    PageSize="10"
    Count="100"
    CurrentPage="0"
/>

Methods

GoToPage(int page, bool forceReload = false)

void

Navigates to the specified page (0-based index).

FirstPage(bool forceReload = false)

void

Navigates to the first page.

PrevPage()

void

Navigates to the previous page.

NextPage()

void

Navigates to the next page.

LastPage()

void

Navigates to the last page.

Reload()

void

Reloads the current page and recalculates pagination.

Styling Classes

The following CSS classes are applied by the Pagination component:

pagination – Root pagination container
pagination-items – Container for all pagination navigation items
pagination-item – Individual pagination item (page numbers, prev/next buttons)
pagination-item.-prev – Previous page button styling
pagination-item.-next – Next page button styling
pagination-item.-page – Page number button styling
pagination-item.-active – Active/current page styling
pagination-item.-disabled – Disabled state for boundary pages
pagination-item.-focused – Focused state for keyboard navigation
pagination-item-icon – Icon styling for navigation arrows
pagination-item-label – Text label styling for prev/next buttons
pagination-item-ellipsis – Ellipsis indicator for truncated ranges
pagination-pagesize-selector – Page size dropdown styling
pagination-pagesize-text – Page size description text styling

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<PaginationLink>` Props

Usage Examples

Styling Classes

`<StudsPagination>` Parameters

Usage Examples

Methods

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Pagination> Props

​<PaginationLink> Props

​Usage Examples

​Styling Classes

​<StudsPagination> Parameters

​Usage Examples

​Methods

​Styling Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<Pagination>` Props

`<PaginationLink>` Props

Usage Examples

Styling Classes

`<StudsPagination>` Parameters

Usage Examples

Methods

Styling Classes