Add accessible labels to pagination links

[michaelbourne]

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(
            $args,
            array(
                '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',
            )
        );

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

[sabernhardt]

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

[michaelbourne]

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

[sabernhardt]

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

[afercia]

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.

Reference:
Success Criterion 2.5.3 Label in Name
​https://www.w3.org/TR/WCAG21/#label-in-name

[xyulex]

I would like to get my hand on it!

Created aria-labels in paginate_links function.

Created aria-labels in paginate_links function.

[sabernhardt]

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.

[webmandesign]

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