Pagination block

[mapk]

While exploring how to add pagination to the Query block, I noticed we need to update the Pagination block (aka Query Pagination block) itself to get it working.

I designed various pagination treatments that we might support. These will require settings and/or style variations to make the visual changes.

Rename the block

I'd like to rename the current "Query Pagination block" to "Pagination block." This naming convention aligns with the Navigation block which includes a "Link block," not a "Navigation Link block."

Settings

Thinking through settings, I've come up with a few to get us started.

• A selectbox for "All buttons / Buttons and Text / Text only."
• Toggle to include/exclude page numbers.
• Toggle to include/exclude "Start" and "End" buttons in addition to the "Prev" and "Next" buttons.
• Condensed page number view (ie. "3 of 22").
• Color settings.
• Border radius settings.
• Maybe even icon arrow options.

Currently

It appears the Query Pagination block hasn't been built quite yet. I see it in the Inserter, but get an error when adding it to the document. I'll start iterating on how these settings will be displayed for this block.

cc @ntsekouras @mariohamann

[fklein-lu]

I'm wondering what the benefit of implementing a new design (and with that markup) is over using the existing WordPress template tags? These are:

1. the_posts_pagination() for archive pages with page numbers.
2. the_posts_navigation() for archive pages with previous and next links.
3. the_post_navigation() for single posts with previous and next links.

These Core functions currently do not work well outside of The Loop, but there's no technical obstacle to making them work in a block.

I'm especially attached to these functions because of the backstory. These functions were introduced in 4.1 to relieve theme developers from having to re-implement the same functionality over and over, in different ways.

There were two main issues with that approach. The first was that some of the functions that WordPress offers, like paginate_links(), are really difficult to work with. The second was that often the markup implemented in these navigations were tag soup, and were missing important accessibility requirements.

So these functions offer solid markup, existing translations when keeping the default strings (as they are part of Core and not the theme), and they are accessible (feel free to correct me here @afercia). Plus if we keep these functions, all existing styles in current themes for this HTML structure will work in the FSE version too.

In addition, and that's my personal opinion, having a million variations of such a simple thing as a pagination is overkill. It should work, it should be accessible, and that's it.

I for sure would not argue for implementing a pagination using dots instead of page numbers, because that makes zero sense. It maybe looks cool, but it is super unusable. Not to mention the challenges of keeping page numbers in the markup for screen readers and search engines while displaying a dot to sighted users. Personally I don't like it, because it mixes the wrong design languages. Dots are used on elements that swipe to show there's more, but this is a pagination, which as the name says shows page numbers.

When we talk about something like "X out of Y" paginations, these make only sense if I can go in and enter a page number, like you do for example in Acrobat Reader, or in the print a page dialogue. Because if I have an interface like that, and I still have to use the next and prev links, what's the point? Also in technical terms this would likely require the use of JavaScript to create the experience that users expect from such an interface.

I find the idea of "First" and "Last" buttons interesting. But what's the use if the pagination includes the first and last page number? Really none at all. In addition there needs to be logic to hide them if they do the same thing as the next and previous buttons because there are not enough pages. Finally I'd say what's the point really? Which user will dig through 22 pages of blog posts? Infinite scroll is what users often expect because of their experiences with mobile optimized sites, plus on content-heavy sites users will likely use the search anyway. So overall it seems like an edge case to me.

Beyond I'm against offering next and previous buttons with borders, with a solid fill, with no borders, etc? That's for the theme to style, just offer one option that's good enough, and the theme will take care of adding the styles that are the most consistent with its overall aesthetics. I do feel that Gutenberg should offer a set of solid default styles, that's in line with all the other blocks, and which respects the Global Styles settings, and that's good enough.

[mariohamann]

First of all: I totally second @fklein-lu concerning current template tags, a11y, "x out of y", "dots" and the "first/last-toggle". Furthermore I want do add some styling concerns:

• "Underlined" for the current state for me doesn't feel right, especially in terms of a11y. (Usually underlined means: Clickable)
• The current "button" state feels quite heavy. I understand that it should say "selected state", but you can't deselect it, therefore it should be more something like "disabled".

Still if this is the way to go:

• "Border radius settings" → shoudl be inherited from global styling

And here are some other option proposals to make it more flexible:

(I don't like the styling of pages... just wanted to add it to make the proposals above possible.)

[mapk]

@fklein-lu I believe those Core functions for pagination are great! However, they need to be reflected in the Pagination block. Adding those as settings can be done, but if there's other settings that can help the user customize their pagination and provide value, we can add those as well.

It would be good to clarify that while I've mocked up many variations of this, it doesn't mean we need to include them all. Several of these could easily be "Style variations" while others would work better as block settings.

I do feel that Gutenberg should offer a set of solid default styles, that's in line with all the other blocks, and which respects the Global Styles settings, and that's good enough.

I agree. Default styles with style variations and some simple settings that allow some basic customization. Again, the examples above don't all need to be implemented, but are rather some thoughts around various pagination designs. It helps us to organize and figure out what to build for.

@mariohamann thanks for jumping into how this might unfold as block settings! Really good to see. I wanted to address some of your feedback as well.

"Underlined" for the current state for me doesn't feel right, especially in terms of a11y. (Usually underlined means: Clickable)

I get this. However, I'll add that tabs in Gutenberg do this very thing in the Inserter panel and in the Settings sidebar.

The current "button" state feels quite heavy. I understand that it should say "selected state", but you can't deselect it, therefore it should be more something like "disabled".

Totally fair. However we can't indicate a different state with color alone. So that's why I opted with either an underline or shape with color. Let's keep that in mind as we continue to iterate.

"Border radius settings" → shoudl be inherited from global styling

Global styles should definitely integrate with this. Especially in use cases that involve more than one Pagination block.

[paaljoachim]

Take a look at https://wordpress.org/plugins/qubely/
It has its own take on Latest posts block settings. It is pretty interesting to check out.
It really gets the mind thinking about which options to include.

Here is the pagination panel. In general the plugin is pretty packed with options.
-The following screenshot is just meant to inspire.-

[mapk]

Rummaging through the potential settings for this block, and considering the many settings of the Query block, I'm considering a minimal, usable, and style-able solution first. This particular solution is simplified, has no settings outside of Style Variations and alignment controls, and provides two of the most common pagination scenarios.

As mentioned above by @fklein-lu:

That's for the theme to style, just offer one option that's good enough, and the theme will take care of adding the styles that are the most consistent with its overall aesthetics.

• Theme will likely provide styling for this block from the get-go.
• Allowing two different style variations gives some control of customization to the user.

Prototype

[carolinan]

After spending too many hours over the past weeks trying to style the buttons and search block options to match a specific design; the thought of having the options described in the first comment, for yet another block, is overwhelming.

It felt exactly like only a person who has already spent months creating the styles for the Gutenberg plugin and knows them inside out, would be able to style these blocks.
It is not meant to be brain surgery. Its close to that difficulty- Gutenberg surgery.

These options only work well when the theme has a neutral design where you don't need to change the defaults.

And please on my bare knees no more inline styles like border radius that can't even be detected with a CSS class... 😄

[ntsekouras]

In addition, and that's my personal opinion, having a million variations of such a simple thing as a pagination is overkill. It should work, it should be accessible, and that's it.

I'm also thinking that we should keep things simple.

[mapk]

I received some feedback yesterday about the prototype above being a good first iteration to finalize and merge. But there were questions around how this might work using child blocks. I explored that a bit and here's how that might look.

[mapk]

Here's a few iterations...

• Highlighting that the user can delete the text from the Prev and Next buttons.
• Changing the page number block settings to just toggle truncation or not.

[bobbingwide]

@mapk In your latest examples the icon for the pagination block looks too similar to the move block icons.
And what exactly is the user moving?

[mapk]

@mapk In your latest examples the icon for the pagination block looks too similar to the move block icons.

This can be remedied. I'm focusing on the flow and features for the Pagination block first, and can reiterate the icon design later. Thanks! 👍

And what exactly is the user moving?

They would move the individual blocks within the Pagination parent block. So one might create a pagination layout that looks like Twenty Nineteen, placing the arrows next to each other.

[bobbingwide]

I must have a different version of Twenty Nineteen. Do you have an example of another theme that does this?

[mapk]

I must have a different version of Twenty Nineteen. Do you have an example of another theme that does this?

My bad. I meant Twenty Sixteen.

[bobbingwide]

Thanks. Twenty Sixteen uses paginate_links(). It's some fancy CSS that styles the previous and next links to be at the end. Does this really need to be an option, or can it just be part of the theme's styling for the pagination links?

[mapk]

Does this really need to be an option

Well if we use child blocks for the interior elements, than the block movers would be included by default.

I believe the first version of this block will treat all pagination elements as one unified block. If we feel it needs to be broken down further into individual child blocks, we can do it in the future.

[kjellr]

@mapk would this block handle previous/next posts pagination too (from within a single post view)? Or would that be a separate block?

[mapk]

@mapk would this block handle previous/next posts pagination too (from within a single post view)? Or would that be a separate block?

I initially thought of it as a different block. But two pagination blocks are one too many. 😉

But now that we're exploring inner blocks for this one, it could work nicely. I just need to include the ability to sync the "Next" and "Previous" buttons with the actual post URL (or however that works), and provide the ability for the "Next" and "Prev" buttons to show the post title if desired.

I'll work these revisions in to see how it feels.

[gibrown]

It would be great to have a maximum number of pages limit as an option (and maybe as a default) in this block. A very common scaling problem for sites when showing links to the last page of an archive (e.g. page 10,000 which then requires sorting 100,000 items on the DB) when:

• crawlers go through every link on every archive page
• users click on the last page

For search especially this is one of the biggest causes of performance problems. Having a maximum default would probably reduce a lot of "WordPress doesn't scale" type problems with a very minor change.