Flask-Paginate

2024.4.12 · active · verified Thu Apr 16

Flask-Paginate provides simple pagination support for Flask applications, making it easy to display large datasets across multiple pages. It handles page number generation, URL building, and integrates with various CSS frameworks like Bootstrap. The current version is 2024.4.12, following a date-based release cadence with frequent updates for bug fixes and compatibility.

Common errors

```
TypeError: Pagination.__init__() got an unexpected keyword argument 'show_first_page_number'
```
cause You are using an outdated argument name for including the first page number in the pagination links.

fix Replace `show_first_page_number` with `include_first_page_number` in your `Pagination` constructor call.
```
ImportError: cannot import name 'Markup' from 'flask'
```
cause This error occurs when running an older version of `flask-paginate` (prior to 2023.10.8) with Flask 3.0 or newer. Flask 3 moved the `Markup` class from `flask` to `markupsafe`.

fix Upgrade `flask-paginate` to version `2023.10.8` or a newer version. `pip install --upgrade flask-paginate`.
```
Pagination links or styling appear broken after upgrading `flask-paginate` or `Flask`.
```
cause The default CSS framework for `flask-paginate` changed from Bootstrap 3 to Bootstrap 4 in version 2021.10.26. Your template HTML might be expecting Bootstrap 3.

fix Explicitly set `css_framework='bootstrap3'` in the `Pagination` constructor if you intend to use Bootstrap 3, or update your HTML templates to comply with Bootstrap 4 or 5 styling, then set `css_framework='bootstrap4'` or `css_framework='bootstrap5'` respectively.

Warnings

breaking The `show_first_page_number` parameter in the `Pagination` constructor was renamed to `include_first_page_number`.
Fix: Update your `Pagination` constructor calls to use `include_first_page_number` instead of `show_first_page_number`.
breaking Older versions of `flask-paginate` (prior to 2023.10.8) are incompatible with Flask 3.0+ due to changes in how `Markup` is imported by Flask.
Fix: Upgrade `flask-paginate` to version `2023.10.8` or newer to ensure compatibility with Flask 3.0 and above. This version internally updates the `Markup` import path.
gotcha The default CSS framework changed from Bootstrap 3 to Bootstrap 4.
Fix: If your templates are still based on Bootstrap 3 or you notice styling issues, explicitly set `css_framework='bootstrap3'` in the `Pagination` constructor, or update your templates to use Bootstrap 4/5 classes. `flask-paginate` also supports 'bootstrap5' directly.

Install

pip install flask-paginate Install stable version

Imports

Pagination
```
from flask_paginate import Pagination
```
The primary class for creating pagination objects.
get_page_parameter
```
from flask_paginate import get_page_parameter
```
Utility to get the page argument from request parameters, supporting custom argument names.
get_per_page_parameter
```
from flask_paginate import get_per_page_parameter
```
Utility to get the per_page argument from request parameters.

Quickstart

This quickstart sets up a basic Flask application with pagination for a list of 100 users. It demonstrates how to retrieve the current page number, slice the data accordingly, and initialize the `Pagination` object. It uses Bootstrap 4 for styling and renders the pagination controls directly using `pagination.render_macro('pagination.html')`.

import os
from flask import Flask, render_template, request
from flask_paginate import Pagination, get_page_parameter

app = Flask(__name__)
app.secret_key = os.environ.get('FLASK_SECRET_KEY', 'a_secret_key_for_dev')

# Sample data
USERS = [str(i) for i in range(1, 101)]

@app.route('/')
def index():
    page = request.args.get(get_page_parameter(), type=int, default=1)
    per_page = 10
    offset = (page - 1) * per_page
    
    users_for_page = USERS[offset:offset + per_page]
    total = len(USERS)

    pagination = Pagination(
        page=page, per_page=per_page, total=total,
        css_framework='bootstrap4',
        record_name='users'
    )

    # In a real app, you would have an 'index.html' template
    # For this example, we'll return a minimal string.
    # In your template, you would use: {{ pagination.render_macro('pagination.html') }}
    return f"""<!doctype html>
<html lang='en'>
<head>
    <meta charset='utf-8'>
    <meta name='viewport' content='width=device-width, initial-scale=1, shrink-to-fit=no'>
    <link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/bootstrap@4.6.2/dist/css/bootstrap.min.css' integrity='sha384-xOolHFLEh07PJGoPkLv1IbcEPTNtaed2xpHsD9ESMhqIYd0nLMwNLD69Npy4HI+N' crossorigin='anonymous'>
    <title>Flask-Paginate Example</title>
</head>
<body>
    <div class='container'>
        <h1>Users</h1>
        <ul>
            {''.join([f'<li>User {user}</li>' for user in users_for_page])}
        </ul>
        <div class='text-center'>
            {pagination.render_macro('pagination.html')}
        </div>
    </div>
</body>
</html>"""

if __name__ == '__main__':
    app.run(debug=True)

view raw JSON →