Struct Pagination 

pub struct Pagination { /* private fields */ }

Pagination query parameters extractor.

Extracts common pagination parameters from the query string:

• page: Current page number (1-indexed, default: 1)
• per_page or limit: Items per page (default: 20, max: 100)
• offset: Alternative to page-based pagination (overrides page if set)

Example

use fastapi_core::Pagination;

#[get("/items")]
async fn list_items(cx: &Cx, pagination: Pagination) -> impl IntoResponse {
    let offset = pagination.offset();
    let limit = pagination.limit();

    // Fetch items from database with offset and limit
    let items = db.fetch_items(offset, limit).await;

    // Return paginated response
    pagination.paginate(items, total_count, "/items")
}

Query String Formats

# Page-based (preferred)
?page=2&per_page=10

# Using limit alias
?page=2&limit=10

# Offset-based (for cursor-style pagination)
?offset=20&limit=10

Configuration

Use PaginationConfig to customize defaults and limits:

use fastapi_core::{Pagination, PaginationConfig};

let config = PaginationConfig::new()
    .default_per_page(50)
    .max_per_page(200);

// The config can be stored in app state and used by handlers

Implementations

impl Pagination

pub fn new(page: u64, per_page: u64) -> Self

Create pagination with specific values.

pub fn from_offset(offset: u64, limit: u64) -> Self

Create pagination from offset and limit.

pub fn page(&self) -> u64

Get the current page number (1-indexed).

pub fn per_page(&self) -> u64

Get the number of items per page.

pub fn limit(&self) -> u64

Alias for per_page() - returns the page size limit.

pub fn offset(&self) -> u64

Calculate the offset for database queries.

If an explicit offset was provided, returns that. Otherwise, calculates from page number: (page - 1) * per_page.

pub fn total_pages(&self, total_items: u64) -> u64

Calculate total number of pages given a total item count.

pub fn has_next(&self, total_items: u64) -> bool

Check if there is a next page.

pub fn has_prev(&self) -> bool

Check if there is a previous page.

pub fn paginate<T>(self, items: Vec<T>, total: u64, base_url: &str) -> Page<T>

Create a paginated response from items.

Arguments

• items - The items for the current page
• total - Total number of items across all pages
• base_url - Base URL for generating Link headers (e.g., “/api/items”)

Trait Implementations

impl Clone for Pagination

fn clone(&self) -> Pagination

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pagination

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Pagination

fn default() -> Self

Returns the “default value” for a type.

impl FromRequest for Pagination

type Error = Infallible

Error type when extraction fails.

async fn from_request( _ctx: &RequestContext, req: &mut Request, ) -> Result<Self, Self::Error>

Extract a value from the request.

impl PartialEq for Pagination

fn eq(&self, other: &Pagination) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Pagination

impl Eq for Pagination

impl StructuralPartialEq for Pagination