[HelpHub] Feedback on Pagination block

[zzap]

URL of the Page with the Issue

https://wordpress.org/documentation/article/pagination-block/

Originally reported by

Report content (issue description)

You explain every click-able item in gory detail, but you don’t explain how pagination relates to query block counts. Obviously, pagination of a list item will only appear when the number of list entries exceeds some limit (eg, 10 items per page). Where is the ’10’ set? What if you have a home page setting limiting the number of pages shown? Where exactly within the ‘query block’ does the pagination need to appear? What if you want to paginate a long body of text? Where is the limit (that has to be exceeded before pagination occurs) set?

By https://profiles.wordpress.org/steerpike58/

Section of Page with the issue

Why is this a problem?

Suggested Fix

[github-actions[bot]]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[karthick-murugan]

/assign

[github-actions[bot]]

Hey @karthick-murugan, thanks for your interest in this issue! 🍪🍪🍪
If you have any questions, do not hesitate to ask them in our #docs Slack channel.
Enjoy and happy contributing ❤️

[karthick-murugan]

Add the below content for Pagination in Query Blocks

Understanding Pagination Behavior in Query Blocks

The Pagination block works in conjunction with the Query Loop block, which dynamically displays lists of posts based on certain criteria. Pagination only appears when the number of items in the query exceeds a predefined limit. Below are key points explaining how pagination works with queries and content limits:

1. Where is the item limit set for pagination to appear?

The number of items per page is determined by the Query Loop block’s settings. By default, WordPress uses the Blog pages show at most setting found in: Dashboard → Settings → Reading This setting controls the number of posts shown per page across archive pages (categories, tags, etc.) and the Query Loop block.

To modify this inside the Query Loop block:

1. Select the Query Loop block in the editor.
2. Open the Block settings panel.
3. Locate the "Posts per page" option and adjust it as needed.
4. If the number of items exceeds this value, the Pagination block will automatically become active.

2. Where should the Pagination block be placed?

The Pagination block must be inside the Query Loop block to function correctly. Typically, it is placed:

• Below the list of posts to allow users to navigate through additional pages of content.
• It should not be placed inside individual post templates, as it applies to the overall query, not single posts.

3. What if a homepage setting limits the number of pages shown?

If your homepage settings restrict the number of displayed posts, it may override the Query Loop’s "Posts per page" setting. Check this setting in: Dashboard → Settings → Reading → "Your homepage displays" If set to show a static page, ensure the Query Loop block within that page is correctly configured.

4. Can pagination be used for long text instead of post lists?

The Pagination block is specifically designed for post lists in a Query Loop. If you need to paginate a long body of text within a single post or page, use:

• The Page Break block, which splits a post into multiple pages.
• A plugin or custom solution for AJAX-based text pagination.

[github-actions[bot]]

Heads up @docs-reviewers - the "[Status] Review" label was applied to this issue.