FacetWP includes built-in accessibility (a11y) support, but it’s disabled by default.

Enable accessibility support

Enable the Load a11y support setting.
Enable the Load a11y support setting in Settings > FacetWP > Settings.

To enable accessibility support, browse to Settings > FacetWP > Settings, and enable the “Load a11y support” setting.

Translate the Pager facet’s aria labels

When the “Load a11y support” setting is enabled, the “page numbers” Pager facet type will have three aria-label attributes in its code: “Go to page #”, “Go to next page” and “Go to previous page”.

These aria labels can be translated with the internationalization function __(), or with the WordPress gettext filter, as demonstrated in this code example.

Enable accessibility support programmatically

To enable FacetWP’s built-in accessibility support programmatically, add the following to your (child) theme’s functions.php:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_load_a11y', '__return_true' );

Note that this does not override the setting. If either the setting is enabled, or the above hook returns true, accessibility support will be enabled.

Add an “aria-live” attribute to a listing

The following code snippet adds an aria-live=”polite” attribute to the <div> with class facetwp-template, generated by a Listing Builder listing template:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_shortcode_html', function( $output, $atts ) {
  if ( isset( $atts['template'] ) ) {
    $output = str_replace( 'class="facetwp-template"', 'class="facetwp-template" aria-live="polite"', $output );
  }
  return $output;
}, 10, 2 );

In WP archive templates or custom WP_Query templates, you can add the attribute manually in your template file.

Add a role=”status” element to the page

If you want to provide a status message (see this working example) to the page after a facet refresh, you could use a “Result counts” type Pager facet for this. This Pager facet type already shows a customizable message with the result counts after each facet refresh.

After adding the facet to the page, add the following snippet to your (child) theme’s functions.php. It will add a role="status" attribute to the HTML of the facet. Make sure to change my_pager_facet_name to the name of your Pager facet:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_shortcode_html', function( $output, $atts ) {
  if ( isset( $atts['facet'] ) && 'my_pager_facet_name' == $atts['facet'] ) { // Change "my_pager_facet_name" to the name of your Pager facet
    $output = str_replace( 'data-name', 'role="status" data-name', $output ); 
  }
  return $output;
}, 10, 2 );

Alternatively, for more control over the status message output, you could add a custom HTML element with a role="status" attribute somewhere on the page:

<p role="status" id="resultsmsg"></p>

Then, add the following snippet to your (child) theme’s functions.php to update the text in this element after each facet refresh. This example will show {#} results returned. Customize the message text in line 7 as needed:

How to use custom JavaScript code?
JavaScript code can be placed in your (child) theme's main JavaScript file. Alternatively, you can add it manually between <script> tags in the <head> section of your (child) theme's header.php file. You can also load it with a hook in your (child) theme's functions.php file, or in the Custom Hooks add-on. To load the code only on pages with facets, use the facetwp_scripts hook. To load it on all pages, use wp_head or wp_footer. Or you can use a code snippets plugin. More info
add_action( 'facetwp_scripts', function() {
  ?>
  <script>
    (function($) {
      document.addEventListener('facetwp-loaded', function() {
        let total_results = FWP.settings.pager.total_rows;
        let resultsmsg = total_results + ' results returned'; // Customize text if needed
        let resultsElement = document.getElementById('resultsmsg');
        resultsElement.innerHTML = resultsmsg;
      });
    })(fUtil);
  </script>
<?php } );

See also

Last updated: May 20, 2024