Make WordPress Core

Opened 2 weeks ago

Last modified 6 days ago

#54260 reopened enhancement

Add accessible labels to pagination links

Reported by: michaelbourne Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: General Keywords: needs-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: https://developer.wordpress.org/reference/functions/paginate_links/

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: https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels#dfn-label

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: https://developer.wordpress.org/reference/functions/get_the_posts_pagination/

        $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 (5)

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

2 weeks 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: https://core.trac.wordpress.org/ticket/54260#ticket

#2 @sabernhardt
8 days 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.

Twenty Twenty-One example

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.)

#3 @michaelbourne
8 days 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.

6 days ago

#5 @sabernhardt
6 days 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

Note: See TracTickets for help on using tickets.