A-Z Listing

The A-Z Listing facet type displays a list of available first letters of the chosen Data Source field content.

Click on a letter to show results starting with that letter. Click the selected letter again, or the “Any” link, to reset the facet.

Available options

Name	Description
Data source	The post attribute or custom field to be used for the first letter.
Default label	Change the default “Any” label. Note: this label is translatable with the facetwp_i18n hook.

How character matching works

By default, the A-Z Listing facet will only show the capital letters A to Z in the standard Latin alphabet.

The first letter of each post is compared to these letters, after being stripped from any accent (or simplified) with WP’s built-in remove_accents() function, before being indexed. When clicking a letter in the facet, the letter is compared to the indexed first letter (without any accents). Upper- and lowercase letters will both match in this process. The result is that, for example, posts starting with n, N, ñ, or Ñ will all be indexed as starting with n/N, without accents, and will all match when clicking N in the facet. If in doubt, you can check for each character how/which accents are removed and how they are returned by this function. Note that it does not only strip accents, but also simplifies some characters in other ways. For example æ becomes ae.

The # character in the facet is an alias for these numbers: 0,1,2,3,4,5,6,7,8,9. This means that any post that has a value that starts with one of these numbers will be in the results when clicking #. If needed, the # character can be removed or replaced with something else.

Use other alphabets, languages, or characters

To replace characters in the facet, add new ones, delete specific ones, or replace the whole A to Z range, you can use the facetwp_alpha_chars hook, which was introduced in version 1.4+ of the add-on.

The following example shows how to add 4 characters to the existing set: 👍, 👎, Æ and Ñ.

The code also contains a second hook in line 17: facetwp_alpha_remove_accents. The purpose of this hook is to remove the remove_accents() function that runs before indexing (as described above). The result is that posts starting with both ñ and Ñ are not stripped of their accents, are indexed as such, and will now match for Ñ, which is exactly what we want (and what also happens for all other non-accent lower/uppercase letters combinations).

The code needs to be added to your (child) theme’s functions.php. Replace my_az_facet_name in line 4 with the name of your A-Z Listing 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
// IMPORTANT: Re-index after adding or changing below code!
add_filter( 'facetwp_alpha_chars', function( $chars, $params ) {

  if ( 'my_az_facet_name' == $params['facet']['name'] ) { // Replace "my_az_facet_name" with the name of your A-Z Listing facet

    // Adds '👍','👎','Æ','Ñ'
    $chars = [ '#', '👍', '👎', 'Æ', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
      'H', 'I', 'J', 'K', 'L', 'M', 'N', 'Ñ', 'O', 'P', 'Q', 'R',
      'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z' ];
  }
  return $chars;

}, 10, 2 );

// Needed when adding characters, like Ñ and Æ. 
// Not needed when ONLY adding emojis, or when ONLY removing characters.
add_filter( 'facetwp_alpha_remove_accents', '__return_false' );

Without the facetwp_alpha_remove_accents hook in line 17, WP’s remove_accents() function would cause posts starting with ñ and Ñ to be indexed as n/N, making them match for N in the facet. In this case, no posts starting with Ñ would be indexed, making Ñ appear as a ghost choice (dimmed) in the facet. If this sounds too complicated, just know that this extra hook is required for the desired behavior. But, if you are only adding emojis, the facetwp_alpha_remove_accents hook is not needed, and you can remove line 17.

Remove the hash character

The # character in the facet is an alias for these numbers: 0,1,2,3,4,5,6,7,8,9. This means that any post that has a value that starts with one of these numbers will be in the results when clicking #.

If you don’t have posts starting with numbers, or if you don’t want this character in the facet, you can remove it by adding the following code to your (child) theme’s functions.php. Make sure to replace my_az_facet_name in line 2 with the name of your A-Z Listing 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_alpha_chars', function( $chars, $params ) {
  if ( 'my_az_facet_name' == $params['facet']['name'] ) { // Replace "my_az_facet_name" with the name of your A-Z Listing facet
    $chars = array_diff( $chars, ['#'] );
  }
  return $chars;
}, 10, 2 );

Customize the hash character

The # character can easily be replaced with something else, using a few lines of CSS. Add the following snippet to your (child) theme’s functions.php to replace it with 0-9:

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_action( 'wp_head', function() {
  ?>
  <style>
    .facetwp-type-alpha .facetwp-alpha[data-id="#"] {
      visibility: hidden;
    }
    .facetwp-type-alpha .facetwp-alpha[data-id="#"]:after {
      content: "0-9"; /* Set the desired text */
      visibility: visible;
    }
  </style>
  <?php
}, 100 );

Use lowercase letters

If you need the letters in the facet to show as lowercase, you can do so with a bit of CSS. 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_action( 'wp_head', function() {
  ?>
    <style>
      .facetwp-type-alpha .facetwp-alpha {
        text-transform: lowercase;
      }
    </style>
  <?php
}, 100 );