Pagination

Page navigation controls for paginated content

The Pagination component provides navigation controls for moving between pages of content. It displays page numbers, previous/next buttons, and handles page state.

Installation

bash
shellui add pagination

Basic Usage

<Pagination CurrentPage="@currentPage"
            CurrentPageChanged="@((page) => currentPage = page)"
            TotalPages="10" />

@code {
    private int currentPage = 1;
}

With Content

Combine pagination with a data list:

Item 1

Description for item 1

Item 2

Description for item 2

Item 3

Description for item 3

<div class="space-y-4">
  @foreach (var item in GetPagedItems())
  {
    <div class="rounded-md border p-4">
      <h3 class="font-medium">@item.Title</h3>
      <p class="text-sm text-muted-foreground">@item.Description</p>
    </div>
  }
</div>

<Pagination CurrentPage="@currentPage"
            CurrentPageChanged="@((page) => currentPage = page)"
            TotalPages="@totalPages" />

@code {
    private record Item(string Title, string Description);

    private const int pageSize = 3;
    private int currentPage = 1;
    private int totalPages => (int)Math.Ceiling(allItems.Count / (double)pageSize);

    private readonly List<Item> allItems = Enumerable.Range(1, 15)
        .Select(i => new Item($"Item {i}", $"Description for item {i}"))
        .ToList();

    private List<Item> GetPagedItems() => allItems
        .Skip((currentPage - 1) * pageSize)
        .Take(pageSize)
        .ToList();
}

Dynamic Page Count

Calculate total pages from data:

<Pagination CurrentPage="@currentPage"
            CurrentPageChanged="@HandlePageChange"
            TotalPages="@((int)Math.Ceiling((double)totalItems / pageSize))" />

@code {
    private int currentPage = 1;
    private int totalItems = 95;
    private int pageSize = 10;

    private async Task HandlePageChange(int page)
    {
        currentPage = page;
        await LoadData();
    }

    private async Task LoadData()
    {
        // Fetch data for current page
    }
}

Custom Styling

<Pagination CurrentPage="@currentPage"
            CurrentPageChanged="@((page) => currentPage = page)"
            TotalPages="20"
            Class="justify-center" />

@code {
    private int currentPage = 1;
}

Composed from parts

New in v0.4: give Pagination child content and build it from PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext and PaginationEllipsis. You decide which page numbers to show, so long ranges can collapse into an ellipsis.

<Pagination>
    <PaginationContent>
        <PaginationItem>
            <PaginationPrevious OnClick="() => Go(page - 1)" />
        </PaginationItem>
        <PaginationItem>
            <PaginationLink IsActive="@(page == 1)" OnClick="() => Go(1)">1</PaginationLink>
        </PaginationItem>
        @if (page > 3)
        {
            <PaginationItem><PaginationEllipsis /></PaginationItem>
        }
        @for (var i = Math.Max(2, page - 1); i <= Math.Min(Total - 1, page + 1); i++)
        {
            var number = i;
            <PaginationItem>
                <PaginationLink IsActive="@(page == number)" OnClick="() => Go(number)">@number</PaginationLink>
            </PaginationItem>
        }
        @if (page < Total - 2)
        {
            <PaginationItem><PaginationEllipsis /></PaginationItem>
        }
        <PaginationItem>
            <PaginationLink IsActive="@(page == Total)" OnClick="() => Go(Total)">@Total</PaginationLink>
        </PaginationItem>
        <PaginationItem>
            <PaginationNext OnClick="() => Go(page + 1)" />
        </PaginationItem>
    </PaginationContent>
</Pagination>

@code {
    private const int Total = 12;
    private int page = 6;

    private void Go(int target) => page = Math.Clamp(target, 1, Total);
}

Each link is a button with OnClick, or an anchor when you set Href, which suits pages that put the page number in the URL.

razor
<Pagination>
    <PaginationContent>
        <PaginationItem><PaginationPrevious Href="/orders?page=1" /></PaginationItem>
        <PaginationItem><PaginationLink Href="/orders?page=1">1</PaginationLink></PaginationItem>
        <PaginationItem><PaginationLink Href="/orders?page=2" IsActive="true">2</PaginationLink></PaginationItem>
        <PaginationItem><PaginationLink Href="/orders?page=3">3</PaginationLink></PaginationItem>
        <PaginationItem><PaginationNext Href="/orders?page=3" /></PaginationItem>
    </PaginationContent>
</Pagination>

API Reference

Property Type Default Description
CurrentPage int 1 The active page number
CurrentPageChanged EventCallback<int> — Callback when page changes; use @bind-CurrentPage
OnPageChange EventCallback<int> — Deprecated: use @bind-CurrentPage; shellui migrate pagination rewrites it
TotalPages int 1 Total number of pages
ChildContent RenderFragment? null Set to compose the pagination from parts; CurrentPage and TotalPages are then unused
Class string? null Additional CSS classes
ClassName string "" Deprecated: use Class

Parts

Component Parameters Purpose
PaginationContent Class The list that holds the items
PaginationItem Class One list item
PaginationLink Href, IsActive, Size (icon or default), OnClick, Class A page link; IsActive marks the current page
PaginationPrevious Href, OnClick, Class The Previous link
PaginationNext Href, OnClick, Class The Next link
PaginationEllipsis Class Stands in for skipped pages

Accessibility

The Pagination component includes:

  • nav element with aria-label="pagination"
  • aria-current="page" on the active page
  • Keyboard navigable with Tab and Enter
  • Previous/Next buttons with aria-label
  • Disabled state for first/last page boundaries

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.