Skip to main content

Getting started with pagination components

Learn how to help users move between pages within apps.

Pagination enables you to present large amounts of data in a more manageable way for your users. Retool provides several components that can help users navigate through pages of data or information:

  • Page Input: An input field to jump to a specific page of data.
  • Pagination: A sequential set of numbered links to navigate through pages.
Demo

These components are independent from the Navigation and Breadcrumbs components, which are primarily used to navigate between apps or between pages.

Features​

Key features of pagination components include

  • Default page and range.
  • Automatic adjustment of page numbers to fit width.
  • Event handlers to perform actions when a page is clicked.
  • Customizeable style.

The Table component automatically paginates tabulated data and has built-in support for server side pagination.

Specify content options​

The Content section of the Inspector contains settings that control the content of the pagination components, such as:

  • Default page.
  • Page count.
  • Add-ons.

You can set the Default page and Page count to an integer or a JavaScript value. The Math.ceil() function is useful for determining the number of pages—for example, you could set the Page count to {{Math.ceil(query1.data.count / 5)}} if you want each page to have five entries.

Page Input enables you to customize the component text using Prefix text and Suffix text add-ons.

Configure user interaction​

The Interaction section of the Inspector enables you to set event handlers, which listen for and handle interactions with your components.

Customize appearance​

You can customize the presentation of your component in the Spacing and Appearance sections of the Inspector. The settings available in the Appearance section depend on the type of component you use.

All components have a Hidden setting, which you can dynamically control with a truthy value that evaluates to true or false. You can also control the hidden property for a component using the .setHidden() method from event handlers and JavaScript queries.

You can also create custom style rules using the Styles setting. Each component has different styles that you can configure, but common ones include colors, fonts, and text styles. Use app-level or organization-level themes to set these styles across all components.

Pagination example​

This guide walks you through an example use case of Pagination, in which a List View displays a custom-built list view of users with the Avatar component. The list displays information about three users at a time and uses the Pagination component to navigate.

Demo

Create queries​

A getUsers query retrieves a list of user information from a PostgreSQL database:

getUsers
select * from users
order by id asc
limit 3 offset {{(pagination1.value - 1) * 3}}

This query returns information from 3 users at a time. It utilizes the value of a Pagination component (which we will create in a moment) to identify the offset for the query. If pagination1.value is 2, then the query returns users with an id of 4, 5, and 6.

An additional query, getCount, retrieves the number of entries in the table:

getCount
select count(*) from users

Add a Pagination component​

Add a Pagination component to the canvas. In this example, each page should contain a list of three users. Set the Page count to {{ (Math.ceil((getCount.data.count)/3)) }}.

  • (getCount.data.count)/3 calculates the number of pages by dividing the total count by the number of users to include per page.
  • Math.ceil() rounds this number up to the nearest whole number. This allows the last page to contain fewer than three users. The users table has 13 users, so there are five pages.

Add a List View component​

Next, add a List View component to the canvas, and update the Data source to getUsers. Add an Avatar component to the first instance of the List View. Update the following settings:

  • Fallback text: {{ getUsers.data.name[i] }}
  • Label: {{ getUsers.data.name[i] }}
  • Caption: {{ getUsers.data.email[i] }}

Now, you have a List View component with an Avatar for each user in the database. Entries are organized into three pages,