Configuration reference

Bundle configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# config/packages/ux_pagination.yaml
ux_pagination:
    items_per_page: 20
    max_offset: 100000
    page_parameter: page
    cursor_parameter: cursor

    navigation:
        mode: sliding
        size: 5

    theme: '@UXPagination/theme/default.html.twig'

    cursor:
        # Optional: defaults to kernel.secret
        secret: '%env(UX_PAGINATION_CURSOR_SECRET)%'

    paginators:
        blog:
            items_per_page: 12
            navigation:
                size: 7

The page size is application-owned. Define its default with items_per_page or select it for a use case with perPage(). UX Pagination does not read a visitor-controlled page-size query parameter.

Set cursor.secret when cursor links need an independent rotation policy. Leave the option unset to reuse kernel.secret. Do not configure null or an empty value: cursor pagination requires a non-empty signing secret. Changing the secret invalidates existing cursor URLs.

navigation.size depends on the mode: the moving window size for sliding, the block size for fixed, and the maximum accepted page count for full.

theme is a complete Twig template name. It defaults to @UXPagination/theme/default.html.twig. A theme passed directly to the Twig function or component overrides it for that rendering only. Pass one template, not a list. Compose application themes with Twig inheritance.

Named paginators

Each entry under paginators inherits the root page, URL and navigation settings, then applies only its explicit overrides:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# config/packages/ux_pagination.yaml
ux_pagination:
    items_per_page: 20
    navigation:
        mode: sliding
        size: 5

    paginators:
        blog:
            items_per_page: 12
            navigation:
                size: 7

        admin:
            items_per_page: 50
            navigation:
                mode: fixed
                size: 10

Inject the profile with a named argument:

1
2
3
4
5

// src/Controller/BlogController.php
public function __construct(
    private readonly PaginatorInterface $blogPaginator,
) {
}

Use #[Target] when the argument name should describe its application role:

1
2
3
4
5
6
7
8

// src/Controller/BlogController.php
use Symfony\Component\DependencyInjection\Attribute\Target;

public function __construct(
    #[Target('blog')]
    private readonly PaginatorInterface $paginator,
) {
}

The explicit service escape hatch is ux_pagination.paginator.<name>:

1
2
3
4
5
6
7
8

// src/Controller/BlogController.php
use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function __construct(
    #[Autowire(service: 'ux_pagination.paginator.blog')]
    private readonly PaginatorInterface $paginator,
) {
}

Paginator names accept letters, digits, dots, dashes and underscores, but must start with a letter or underscore. Names that resolve to the same autowiring target are rejected.

theme and cursor.secret stay global. The theme belongs to the renderer, and the signing secret is an application security invariant rather than a paginator preference.

Application entry points

Inject PaginatorInterface and choose the smallest entry point that exposes the policy the application needs:

paginate() is the one-line application default:

1
2

// src/Controller/ProductController.php
$products = $paginator->paginate($repository->createListQuery());

The other entry points return immutable builders and end with ->paginate(). Cursor pagination intentionally has no argument-heavy shortcut: ordering, page size, explicit cursor and application context remain named configuration steps.

Builder reference

Every builder method is immutable and returns a clone. Configure navigation policy and URL composition on the builder, then call paginate().

Choose the total strategy explicitly:

total() accepts a non-negative integer or a callable returning one. The callable runs lazily and at most once, so an invokable Symfony service can be passed directly, without a bundle-specific provider interface.

Do not combine lookahead() with total() or throwOnOutOfRange(). Lookahead deliberately avoids the exact total those policies need, and the builder rejects both combinations.

URL methods configure the builder, not an already-created result. This keeps one URL policy for the complete pagination lifecycle:

1
2
3
4
5
6
7

// src/Controller/ProductController.php
$products = $paginator
    ->query($repository->createFilteredQuery($filters))
    ->excludeQueryParameters('debug')
    ->queryParameters(['category' => $category->getSlug()])
    ->fragment('results')
    ->paginate();

Cursor builder reference

Result reference

All pagination results implement PaginationInterface. The result interfaces intentionally expose only the state and links consumers need for iteration, rendering and serialization. Application services can type against PaginationInterface when they only iterate items or expose adjacent navigation:

Numbered and lookahead results implement NumberedPaginationInterface:

Cursor results implement CursorPaginationInterface:

Twig function

The function has an explicit signature:

1
2
3
4
5
6
7
8

ux_pagination(
    pagination,
    attributes = {},
    theme = null,
    show_info = true,
    navigation_attributes = {},
    link_attributes = {},
)

attributes apply to the root <nav>, navigation_attributes apply to the controls container, and link_attributes apply to every real link. link_attributes also accepts a closure for link-specific attributes. See Rendering and customization for the closure context and the escaping rules.

1
2
3
4
5
6
7
8
9
10
11
12

{{ ux_pagination(
    products,
    {
        id: 'product-pages',
        class: 'product-pagination',
        'aria-label': 'Product results',
    },
    theme: '@UXPagination/theme/tailwind.html.twig',
    show_info: false,
    navigation_attributes: {class: 'product-pagination__controls'},
    link_attributes: {class: 'product-pagination__link'},
) }}

The Twig component exposes the same contract with normal component attributes:

1
2
3
4
5
6
7
8
9

<twig:ux:pagination
    :pagination="products"
    theme="@UXPagination/theme/tailwind.html.twig"
    :showInfo="false"
    id="product-pages"
    class="product-pagination"
    :navigationAttributes="{class: 'product-pagination__controls'}"
    :linkAttributes="{class: 'product-pagination__link'}"
/>

UX Pagination ships no browser runtime. Generic HTML and data-* attributes remain available for application integrations, without a second bundle-specific options language. The bundle implements no prefetch policy. Applications using Turbo can rely on Turbo's prefetch facilities.