Make WordPress Core

Opened 3 years ago

Last modified 12 months ago

#54260 reopened enhancement

Add accessible labels to pagination links

Reported by: michaelbourne's profile michaelbourne Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: accessibility Cc:


The default behavior of paginate_links is to output link text with no context around the page numbers that the text represents.

WP Ref:

This is a sample of the default output:

<div class="nav-links">
  <span aria-current="page" class="page-numbers current">1</span>
  <a class="page-numbers" href="">2</a>
  <span class="page-numbers dots">…</span>
  <a class="page-numbers" href="">13</a>
  <a class="next page-numbers" href="">Next</a></div>

I believe the more accessible output would be this:

<div class="nav-links">
  <span aria-current="page" class="page-numbers current">1</span>
  <a class="page-numbers" href="" aria-label="Page 2">2</a>
  <span class="page-numbers dots">…</span>
  <a class="page-numbers" href="" aria-label="Page 13">13</a>
  <a class="next page-numbers" href="" aria-label="Next Page">Next</a></div>

This falls short of what most of us would call an acceptable level of readability for users with assistive technologies. A few small code changes could alleviate this, I believe.

W3 Ref:

To go along with this, a small change to get_the_posts_pagination should be used to supply the translatable string for this label.

WP Ref:

        $args = wp_parse_args(
                'mid_size'           => 1,
                'prev_text'          => _x( 'Previous', 'previous set of posts' ),
                'next_text'          => _x( 'Next', 'next set of posts' ),
                'screen_reader_text' => __( 'Posts navigation' ),
                'aria_label'         => __( 'Posts' ),
                'links_aria_label'   => __( 'Page' ),
                'class'              => 'pagination',

Change History (11)

This ticket was mentioned in PR #1755 on WordPress/wordpress-develop by michaelbourne.

3 years ago

  • Keywords has-patch added

Create a new default $arg in paginate_links and use aria-label to provide context to page links for better accessibility.

Trac ticket:

#2 @sabernhardt
3 years ago

Hi, and thanks for the report!

In ticket:24709, the before_page_number and after_page_number arguments were created so themes could add (non-visual) text to each of the page links.

The Twenty Twenty-One example has visible text.

If ARIA labels are included automatically, they should not override the context provided in these two arguments. (It might be worth using the label attributes as a fallback.)

Last edited 12 months ago by sabernhardt (previous) (diff)

#3 @michaelbourne
3 years ago

  • Resolution set to invalid
  • Status changed from new to closed

Hi @sabernhardt

I completely overlooked the fact I could use HTML in those args. Screen reader text is always better than an aria label if it can be used. I guess that renders this trac ticket (and the connected PR) moot!

Appreciate the second set of eyes, sometimes it's easy to drown in the codex :)

This ticket was mentioned in Slack in #accessibility by sabernhardt. View the logs.

3 years ago

#5 @sabernhardt
3 years ago

  • Keywords needs-patch added; has-patch removed
  • Milestone changed from Awaiting Review to Future Release
  • Resolution invalid deleted
  • Status changed from closed to reopened
  • Version 5.8.1 deleted

Reopening to consider the possibility of adding an aria-label or something else if the theme does not include either the before_page_number or after_page_number argument

#6 @afercia
19 months ago

Worth reminding that providing an accessible name (via the aria-label) that is different and, in a way, unexpected compared to the visible text does impact speech recognition users. For example:

  • As a sighted speech recognition user, I see a link with text 2.
  • Based on that, I'd try to issue a voice command like Click 2.
  • The command would likely fail because the link accessible name (the name the speech recognition software perceives) would be Page 2.

In general, hidden labels/text (whether it's an aria-label or visually hidden text) may help blind screen reader users but they may be misleading or even an actual barrier for sighted users. It's always best to show visible text. If more context is needed, we should just add visible text.

Success Criterion 2.5.3 Label in Name

#7 @xyulex
13 months ago

I would like to get my hand on it!

This ticket was mentioned in PR #4429 on WordPress/wordpress-develop by @xyulex.

13 months ago

  • Keywords has-patch added; needs-patch removed

Created aria-labels in paginate_links function.

This ticket was mentioned in PR #4429 on WordPress/wordpress-develop by @xyulex.

13 months ago

Created aria-labels in paginate_links function.

#10 @sabernhardt
12 months ago

Instead of adding text to individual links (whether visible, screen reader only, or an aria-label), could the default aria-label for the nav container give more context? Right now, the label for the posts navigation is simply "Posts" but something like "Pages of posts" might help.

#11 @webmandesign
12 months ago

I think adding a filter for paginate_links() $args would help in this case. See #53859

Especially nowadays when building a block theme there is no way for me to change the HTML output of the Pagination block other than tweaking its HTML output (via render_block filter). This is not optimal and filtering the $args would provide more flexibility I think.

(I am building accessibility ready themes, so I would like to improve the HTML output of pagination too.)

Note: See TracTickets for help on using tickets.