During Wishathon 2025, we worked on T394637: Revamp pagination page navigation and we worked on a WIP version of the Codex Pagination component. I'm sharing all relevant design details here so we can continue working on this later.

The design of this Codex Pagination component is based on the pagination created for the Table.

The pagination will contain the following customizable elements:

• Select: to choose the number of items to show per page. The default number will be 10, and then it will be customizable to 20, 50, and 100 items.
• Text indicator: to show the items being displayed (e.g. Showing results 1–10 of 999,999)
• Buttons: to navigate the pages. There will be buttons to navigate from Previous/Next pages and from First/Last pages.

These elements could be shown/hidden according to each pagination's case:

@CCiufo-WMF We are considering this work as part of our next wishathon. Is there a particular reason why this was moved to the backlog? Is the proposed designs by @bmartinezcalvo good to go as is? Any help on how to move this forward is greatly appreciated. Thanks.

@dmaza I can't remember exactly, but looking at the timing of when I moved it to the backlog, I think it was just a matter of not seeing it as a priority as Design-System-Team was winding down. Originally, we intentionally put off creating a pagination component when we were building the table component, so as not to complicate the design of that component.

I believe our original plans were to build the pagination component and then use it in the table, but we decided to cut scope and just build a table with non-reusable pagination built in. That's something to keep in mind if this standalone pagination component is pursued.

I think @DTorsani-WMF would be the right person to weigh in on this component going forward though!

Thank you @CCiufo-WMF. I wanted to make sure there weren't any known blockers or dependencies before this could be picked on.

@DTorsani-WMF any thoughts?

@dmaza I don't think there are any current blockers other than resources and time. So if you are able to work on this that would be great! Please let me know if you need any design support or have any questions during the process of working on it.

I see that there already is a TablePager as part of the Table component:

https://gerrit.wikimedia.org/r/plugins/gitiles/design/codex/+/refs/heads/main/packages/codex/src/components/table/TablePager.vue

It looks like it does most (if not all) that we need and matches the designs (for the most part). For the task, I think we could make the TablePager into a reusable component on it's own.

Also, assume we would put it in components-wip? though not sure if that would make it usable in the Table component, or what the process is to get a component out of wip?

That sounds good to me, but will let @Catrope weigh in on your question.

For the overall wish from the community for improved pagination on the special pages, we are now not sure that a Pagination vue component would be what we need.

We might just need HTML elements with codex styles.

https://meta.wikimedia.org/wiki/Community_Wishlist/W186

In T368423#11380266, @aude wrote:

For the overall wish from the community for improved pagination on the special pages, we are now not sure that a Pagination vue component would be what we need.

We might just need HTML elements with codex styles.

https://meta.wikimedia.org/wiki/Community_Wishlist/W186

We could try and do something similar to what was done for HTMLForm "displayFormat" and support the current navigation output and a "codex" looking one? Would that make sense?

We already have pager/CodexTablePager.php ... could we extract getNavigationBar() (and some of its associated methods) out into a trait, and then try deleting getNavigationBar() from other Pager classes and useing the trait instead?

I created a new task that is more specific to the wishlist request:

https://phabricator.wikimedia.org/T410338

@Cparle extracting getNavigationBar() from CodexTablePager looks like a very good starting point for what we need. Thanks for pointing us to that.

@bmartinezcalvo right now we don't display "Showing results 1–10 of 999,999" and we can't commit to doing this in general - for search we retrieve a maximum of 10k results, and for database queries they're structured (for efficiency) in such a way that it's not possible to know the size of the resultset the user is paging through

El T368423#11387936, @Cparle escribió:

@bmartinezcalvo right now we don't display "Showing results 1–10 of 999,999" and we can't commit to doing this in general - for search we retrieve a maximum of 10k results, and for database queries they're structured (for efficiency) in such a way that it's not possible to know the size of the resultset the user is paging through

The "Showing results 1–10 of 999,999" results is an example of how it would look with a large number. The 999,999 should actually be the number of the rows/items/results as currently implemented in the Table's pagination in Codex.

Similar to how the number of pages is currently shown when searching for results.

That number for search results is kind of a weird one - it shows you the total number of results, but you can't actually page through them all (you can only get the first 10k) - here's an example. Maybe that doesn't matter, because it's v unlikely anyone will page that far? If it doesn't then I guess we can show the total

For most pages that use pagers inside MediaWiki (e.g. https://en.wikipedia.org/wiki/Special:Log) we actually don't know the total number of pages (because we're trying to avoid expensive database queries), and so can't show it

I guess we can add it if/when we know it, and not otherwise? @tstarling thoughts?

Actually now I think of it - we also don't know where we are in the resultset (we kinda do for search, but it's hacky), so we can't even say "Showing results 250-300 of many"

For context - the way paging works on the php side is we don't page based on numbers, but using database indices. If you look at https://en.wikipedia.org/wiki/Special:Log and click "next" and look at the url in your browser, you'll see that the offset value isn't a number. It's tricky to explain in detail - I can set up a meeting to attempt an explanation if you like?

@bmartinezcalvo I see that in the dropdown for results per page you have "X results" rather than "X rows" which is what's in Codex right now. I think that makes sense (or maybe something like this image below)

... but maybe better still would be to use "X results per page" in each item in the dropdown instead? I think that's clearer than "rows"

El T368423#11388992, @Cparle escribió:

@bmartinezcalvo I see that in the dropdown for results per page you have "X results" rather than "X rows" which is what's in Codex right now. I think that makes sense (or maybe something like this image below)

... but maybe better still would be to use "X results per page" in each item in the dropdown instead? I think that's clearer than "rows"

In Table's pagination, we used "rows", while in the specifications for this pagination I used "results" as something more generic that aligned better with the Search results prototype where I used this pagination component. Either "results" or "items" could work, but in order to be aligned with the Table's pagination, the "results" word should be included within the Select, not outside.

El T368423#11388914, @Cparle escribió:

Actually now I think of it - we also don't know where we are in the resultset (we kinda do for search, but it's hacky), so we can't even say "Showing results 250-300 of many"

If it's not possible to show the number of results (e.g. "Showing results 1–20 of 999"), I would show at least the results listed in that page (e.g. "Showing results 1–20") so the user knows in which page they are.

In T368423#11389014, @bmartinezcalvo wrote:

Either "results" or "items" could work, but in order to be aligned with the Table's pagination, the "results" word should be included within the Select, not outside.

Ok ... so is it ok to change the message to "X results" for all codex table pagination everywhere? Or maybe "X results per page"?

El T368423#11389025, @Cparle escribió:

In T368423#11389014, @bmartinezcalvo wrote:

Either "results" or "items" could work, but in order to be aligned with the Table's pagination, the "results" word should be included within the Select, not outside.

Ok ... so is it ok to change the message to "X results" for all codex table pagination everywhere? Or maybe "X results per page"?

I mean, when possible I would show "Showing results 1–20 of 999". But in case it's not possible, we can hide the 999 and just show "Showing results 1–20" if there are restrictions to show the total number of items where the pagination is being used.

I meant inside the select - so like this

The text inside that box is a Codex msg, so if I change it then it changes everywhere there is pagination in Codex. I think it probably should change, because "rows" doesn't really make much sense

El T368423#11389083, @Cparle escribió:

I meant inside the select - so like this

The text inside that box is a Codex msg, so if I change it then it changes everywhere there is pagination in Codex. I think it probably should change, because "rows" doesn't really make much sense

If we will use one single text for all places where pagination is being used, I would use then "20 items" since I think it's the most generic. I would avoid longer names to avoid issues on small screens with translations to longer languages.

padding: 12px on .cdx-table-pager is pretty weird when it's already inside #mw-content-text, which has plenty of space around it. It makes "n items" look like it's randomly indented.

@dmaza Should I keep this in progress? Do you think we might go back to it in a future Wishathon?

In T368423#11591410, @KSiebert wrote:

@dmaza Should I keep this in progress? Do you think we might go back to it in a future Wishathon?

We didn't have to work on the Codex side of it (which this task is about). We can probably move this one back to the backlog

Most of the work we did was on a separate task created by @aude T410338, and all the patches submitted are referencing it. That one can probably be closed. @Cparle @aude , thoughts on closing T410338: New Codex UI for pagination / page navigation in Special pages?