The pagination component

Navigation links to go to the first, previous, next, or last page of a dataset. Useful when data is divided into pages, each containing a fixed number of rows.

This component only handles the display of pagination. Your sql queries are responsible for filtering data based on the page number passed as a URL parameter.

This component is typically used in conjunction with a table, list, or card component.

The pagination component displays navigation buttons (first, previous, next, last) customizable with text or icons.

For large numbers of pages, an offset can limit the visible page links.

A minimal example of a SQL query that uses the pagination would be:

select 'table' as component;
select * from my_table limit 100 offset $offset;

select 'pagination' as component;
with recursive pages as (
    select 0 as offset
    union all
    select offset + 100 from pages
    where offset + 100 < (select count(*) from my_table)
)
select 
    (offset/100+1) as contents,
    sqlpage.link(sqlpage.path(), json_object('offset', offset)) as link,
    offset = coalesce(cast($offset as integer), 0) as active
from pages;

For more advanced usage, the pagination guide provides a complete tutorial.

Introduced in SQLPage v0.40.0.

Top-level parameters

name required type description
circle

BOOLEAN

 Whether to use circle version of the pagination.
class

TEXT

 class attribute added to the container in HTML. It can be used to apply custom styling to this item through css. Added in v0.18.0.
first_disabled

BOOLEAN

 disables the button to go to the first page.
first_link

URL

 A target URL to which the user should be directed to get to the first page. If none, the link is not displayed.
first_title

TEXT

 The text displayed on the button to go to the first page.
id

TEXT

 id attribute added to the container in HTML. It can be used to target this item through css or for scrolling to this item through links (use "#id" in link url).
last_disabled

BOOLEAN

 disables the button to go to the last page.
last_link

URL

 A target URL to which the user should be directed to get to the last page. If none, the link is not displayed.
last_title

TEXT

 The text displayed on the button to go to the last page.
next_disabled

BOOLEAN

 Disables the button to go to the next page.
next_link

URL

 A target URL to which the user should be directed to get to the next page. If none, the link is not displayed.
next_title

TEXT

 The text displayed on the button to go to the next page.
outline

BOOLEAN

 Whether to use outline version of the pagination.
previous_disabled

BOOLEAN

 disables the button to go to the previous page.
previous_link

URL

 A target URL to which the user should be directed to get to the previous page. If none, the link is not displayed.
previous_title

TEXT

 The text displayed on the button to go to the previous page.

Row-level parameters

name required type description
contents REQUIRED

INTEGER

 Page number.
active

BOOLEAN

 Whether the link is active or not. Defaults to false.
link

URL

 A target URL to which the user should be redirected to view the requested page of data.
offset

BOOLEAN

 Whether to use offset to show only a few pages at a time. Usefull if the count of pages is too large. Defaults to false

Example 1

This is an extremely simple example of a pagination component that displays only the page numbers, with the first page being the current page.

select 
    'pagination' as component;
select 
    1    as contents,
    '?component=pagination&page=1' as link,
    TRUE as active;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;

Result

Example 2

The ouline style adds a rectangular border to each navigation link.

select 
    'pagination' as component,
    TRUE         as outline;
select 
    1    as contents,
    '?component=pagination&page=1' as link,
    TRUE as active;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;

Result

Example 3

The circle style adds a circular border to each navigation link.

select 
    'pagination' as component,
    TRUE         as circle;
select 
    1    as contents,
    '?component=pagination&page=1' as link,
    TRUE as active;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;

Result

Example 4

The following example implements navigation links that can be enabled or disabled as needed. Since a navigation link does not appear if no link is assigned to it, you must always assign a link to display it as disabled.

select 
    'pagination'            as component,
    '?component=pagination' as first_link,
    TRUE                    as first_disabled,
    '?component=pagination' as previous_link,
    TRUE                    as previous_disabled,
    '#?page=2'              as next_link,
    '#?page=3'              as last_link;
select 
    1    as contents,
    '?component=pagination&page=1' as link,
    TRUE as active;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;

Result

Example 5

Instead of using icons, you can apply text to the navigation links.

select 
    'pagination'            as component,
    'First'                 as first_title,
    'Last'                  as last_title,
    'Previous'              as previous_title,
    'Next'                  as next_title,
    '?component=pagination' as first_link,
    TRUE                    as first_disabled,
    '?component=pagination' as previous_link,
    TRUE                    as previous_disabled,
    '#?page=2'              as next_link,
    '#?page=3'              as last_link;
select 
    1    as contents,
    '?component=pagination&page=1' as link,
    TRUE as active;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;

Result

Example 6

If you have a large number of pages to display, you can use an offset to represent a group of pages.

select 
    'pagination' as component,
    '#?page=1'   as first_link,
    '#?page=3'   as previous_link,
    '#?page=4'   as next_link,
    '#?page=99'  as last_link;
select 
    1 as contents,
    '?component=pagination&page=1' as link;
select 
    2 as contents,
    '?component=pagination&page=2' as link;
select 
    3 as contents,
    '?component=pagination&page=3' as link;
select 
    4    as contents,
    '?component=pagination&page=4' as link,
    TRUE as active;
select 
    5 as contents,
    '?component=pagination&page=5' as link;
select 
    6 as contents,
    '?component=pagination&page=6' as link;
select 
    TRUE as offset;
select 
    99 as contents,
    '?component=pagination&page=99' as link;

Result

See also: other components

alert authentication big_number breadcrumb button card carousel chart code columns cookie csv datagrid debug divider download dynamic empty_state foldable form hero html http_header json list log login map modal pagination redirect rss shell status_code steps tab table text timeline title tracking