View as Markdown

Pagination

Pagination with page navigation, next and previous links.

Loading... 
<twig:Pagination>
    <twig:Pagination:Content>
        <twig:Pagination:Item>
            <twig:Pagination:Previous href="#" />
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">1</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#" active>2</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">3</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Ellipsis />
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Next href="#" />
        </twig:Pagination:Item>
    </twig:Pagination:Content>
</twig:Pagination>

Installation

bin/console ux:install pagination --kit shadcn

That's it!

Install the following Composer dependencies:

composer require symfony/ux-icons tales-from-a-dev/twig-tailwind-extra:^1.0.0

Copy the following file(s) into your Symfony app:

templates/components/Pagination.html.twig 
{# @block content The pagination structure, typically a `Pagination:Content` #}
<nav
    data-slot="pagination"
    aria-label="pagination"
    role="navigation"
    class="{{ ('mx-auto flex w-full justify-center ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ attributes.without('class') }}
>
    {%- block content %}{% endblock -%}
</nav>
templates/components/Pagination/Content.html.twig 
{# @block content The pagination items, typically multiple `Pagination:Item` components #}
<ul
    data-slot="pagination-content"
    class="{{ ('flex items-center gap-0.5 ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ attributes.without('class') }}
>
    {%- block content %}{% endblock -%}
</ul>
templates/components/Pagination/Ellipsis.html.twig 
<span
    aria-hidden="true"
    data-slot="pagination-ellipsis"
    class="{{ ('flex size-8 items-center justify-center [&_svg:not([class*=\'size-\'])]:size-4 ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ attributes.without('class') }}
>
    <twig:ux:icon name="lucide:more-horizontal" />
    <span class="sr-only">More pages</span>
</span>
templates/components/Pagination/Item.html.twig 
{# @block content The pagination item content, typically a `Pagination:Link` #}
<li data-slot="pagination-item" {{ attributes }}>
    {%- block content %}{% endblock -%}
</li>
templates/components/Pagination/Link.html.twig 
{# @prop active boolean Whether this is the current page. Defaults to `false` #}
{# @block content The page number or navigation icon #}
{%- props active = false -%}
<twig:Button
    as="a"
    variant="{{ active ? 'outline' : 'ghost' }}"
    size="icon"
    aria-current="{{ active ? 'page' : false }}"
    data-slot="pagination-link"
    data-active="{{ active ? 'true' : 'false' }}"
    {{ ...attributes }}
>
    {{- block(outerBlocks.content) -}}
</twig:Button>
templates/components/Pagination/Next.html.twig 
{# @prop text string The label text. Defaults to `Next` #}
{%- props text = 'Next' -%}
<twig:Pagination:Link
    aria-label="Go to next page"
    size="default"
    class="{{ ('ltr:pr-1.5! rtl:pe-1.5! ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ ...attributes.without('class') }}
>
    <span class="hidden sm:block">{{ text }}</span>
    <twig:ux:icon name="lucide:chevron-right" data-icon="inline-end" class="rtl:rotate-180" />
</twig:Pagination:Link>
templates/components/Pagination/Previous.html.twig 
{# @prop text string The label text. Defaults to `Previous` #}
{%- props text = 'Previous' -%}
<twig:Pagination:Link
    aria-label="Go to previous page"
    size="default"
    class="{{ ('ltr:pl-1.5! rtl:ps-1.5! ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ ...attributes.without('class') }}
>
    <twig:ux:icon name="lucide:chevron-left" data-icon="inline-start" class="rtl:rotate-180" />
    <span class="hidden sm:block">{{ text }}</span>
</twig:Pagination:Link>

Happy coding!

Usage

<twig:Pagination>
    <twig:Pagination:Content>
        <twig:Pagination:Item>
            <twig:Pagination:Previous href="#" />
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">1</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#" active>2</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">3</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Ellipsis />
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Next href="#" />
        </twig:Pagination:Item>
    </twig:Pagination:Content>
</twig:Pagination>

Examples

Simple

A simple pagination with only page numbers.

Loading... 
<twig:Pagination>
    <twig:Pagination:Content>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">1</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#" active>2</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">3</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">4</twig:Pagination:Link>
        </twig:Pagination:Item>
        <twig:Pagination:Item>
            <twig:Pagination:Link href="#">5</twig:Pagination:Link>
        </twig:Pagination:Item>
    </twig:Pagination:Content>
</twig:Pagination>

Icons Only

Use just the previous and next buttons without page numbers. This is useful for data tables with a rows per page selector.

Loading... 
<div class="flex items-center justify-between gap-4">
    <twig:Field orientation="horizontal" class="w-fit">
        <twig:Field:Label for="select-rows-per-page">Rows per page</twig:Field:Label>
        <twig:Select id="select-rows-per-page" class="w-20">
            <option value="10">10</option>
            <option value="25" selected>25</option>
            <option value="50">50</option>
            <option value="100">100</option>
        </twig:Select>
    </twig:Field>
    <twig:Pagination class="mx-0 w-auto">
        <twig:Pagination:Content>
            <twig:Pagination:Item>
                <twig:Pagination:Previous href="#" />
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Next href="#" />
            </twig:Pagination:Item>
        </twig:Pagination:Content>
    </twig:Pagination>
</div>

RTL

To enable RTL support, set the dir="rtl" attribute on the root element.

Loading... 
<div class="flex flex-col gap-8">
    {# Arabic #}
    <twig:Pagination dir="rtl">
        <twig:Pagination:Content>
            <twig:Pagination:Item>
                <twig:Pagination:Previous href="#" text="السابق" />
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#">١</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#" active>٢</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#">٣</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Ellipsis />
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Next href="#" text="التالي" />
            </twig:Pagination:Item>
        </twig:Pagination:Content>
    </twig:Pagination>

    {# Hebrew #}
    <twig:Pagination dir="rtl">
        <twig:Pagination:Content>
            <twig:Pagination:Item>
                <twig:Pagination:Previous href="#" text="הקודם" />
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#">1</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#" active>2</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Link href="#">3</twig:Pagination:Link>
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Ellipsis />
            </twig:Pagination:Item>
            <twig:Pagination:Item>
                <twig:Pagination:Next href="#" text="הבא" />
            </twig:Pagination:Item>
        </twig:Pagination:Content>
    </twig:Pagination>
</div>

API Reference

Component Pagination

Block Description
content The pagination structure, typically a Pagination:Content

Component Pagination:Content

Block Description
content The pagination items, typically multiple Pagination:Item components

Component Pagination:Item

Block Description
content The pagination item content, typically a Pagination:Link

Component Pagination:Link

Prop Type Description
active boolean Whether this is the current page. Defaults to false
Block Description
content The page number or navigation icon

Component Pagination:Next

Prop Type Description
text string The label text. Defaults to Next

Component Pagination:Previous

Prop Type Description
text string The label text. Defaults to Previous