Alphabetical (A–Z, #, 0–9) index for any post type. Shortcode, Gutenberg block, REST API, WooCommerce auto-mount, multilingual, WCAG AA.

mansoormunib

Alphabetical Pagination (formerly WP-SNAP Extended!) builds an alphabetical index of post titles across any public post type. Visitors jump straight to a letter (A, B, C …), browse a paginated list of matching posts, and click through to each post’s permalink.
Built for modern WordPress: PHP 8.1+ typed classes, schema-validated options, prepared SQL throughout, semantic markup, no jQuery dependency, no bundled CSS framework, zero front-end JS by default.
<h4>Why use it</h4>
<ul>
<li>Modern PHP 8.1+ architecture — typed <code>final</code> classes under <code>includes/</code>, every superglobal sanitised, every echoed value escaped, every DB call prepared.</li>
<li>Three embedding surfaces — <code>[alphabetical_pagination]</code> shortcode, <code>alphabetical_pagination()</code> template tag, and a native Gutenberg block (<code>wp-snap-ext/index</code>).</li>
<li>WooCommerce auto-mount — one click renders the index above the shop loop or product category archives via the native <code>woocommerce_before_shop_loop</code> action. No DOM hacks, no <code>posts_where</code> SQL filter injection.</li>
<li>15 bundled alphabet packs — English, Arabic, Chinese (Pinyin), German, Spanish, French, Greek, Hebrew, Hindi, Hungarian, Korean (Hangul Jamo), Russian, Thai, Turkish, Urdu.</li>
<li>WPML + Polylang aware — the letter cache keys on current language, so translated post sets render and cache per-language automatically.</li>
<li>REST API — <code>GET /wp-json/wp-snap-ext/v1/letters</code> and <code>/posts</code> for headless / React / app integrations.</li>
<li>Documented developer hook API — <code>do_action</code>/<code>apply_filters</code> at every render path so agencies can customise without forking.</li>
<li>Transient letter-availability cache — letter counts cached as transients, busted on <code>save_post</code>. Configurable TTL.</li>
<li>ACF excerpt fallback — supports top-level, sub-field, and deep flexible-content / repeater / group lookups via recursive <code>get_fields()</code> walk.</li>
<li>WCAG 2.1 AA — <code><nav aria-label></code>, <code>aria-current="page"</code>, <code>aria-disabled</code> on empty letters, explicit <code>role="list"</code> / <code>role="listitem"</code> (Safari + VoiceOver list-stripping fix), descriptive per-letter <code>aria-label</code>, visible focus outlines.</li>
<li>Zero front-end JS dependency by default — no jQuery, no Bootstrap, no FontAwesome. Stylesheet is ~1 KB.</li>
</ul>
<h4>2.3.0 feature surface</h4>
<ul>
<li>Gutenberg block — server-rendered <code>wp-snap-ext/index</code> block (no JS build pipeline required). Renders identically to the shortcode + template tag.</li>
<li>WooCommerce auto-mount — toggle in Settings → Alphabetical Pagination → WooCommerce. Mount hook selectable: <code>woocommerce_before_shop_loop</code> (default), <code>woocommerce_archive_description</code>, or <code>woocommerce_before_main_content</code>.</li>
<li>REST API endpoints — <code>/wp-json/wp-snap-ext/v1/letters</code> returns <code>[{ letter, count, href }]</code>; <code>/wp-json/wp-snap-ext/v1/posts</code> returns paginated post payloads.</li>
<li>Developer hooks:
<ul>
<li><code>do_action( 'wp_snap_ext/before_render', $context )</code></li>
<li><code>apply_filters( 'wp_snap_ext/pre_render', $html, $post_type, $display, $args )</code> — short-circuit</li>
<li><code>apply_filters( 'wp_snap_ext/query_args', $args, $context )</code></li>
<li><code>apply_filters( 'wp_snap_ext/letter_href', $href, $letter, $base )</code></li>
<li><code>apply_filters( 'wp_snap_ext/excerpt', $excerpt, $post_id )</code></li>
<li><code>apply_filters( 'wp_snap_ext/render', $html, $post_type, $display, $args )</code></li>
<li><code>do_action( 'wp_snap_ext/after_render', $html, $context )</code></li>
</ul>
</li>
<li>Transient letter-availability cache — keyed by post_type, taxonomy, term, current language, alphabet pack, and menumisc setting. Invalidated on <code>save_post</code>, <code>deleted_post</code>, <code>trashed_post</code>, <code>untrashed_post</code>, and <code>switch_blog</code>. Default TTL 1 hour, configurable.</li>
<li>WPML + Polylang awareness — cache key includes <code>wpml_current_language</code> or <code>pll_current_language()</code>; WP_Query runs with <code>suppress_filters => false</code> so translated post sets get filtered.</li>
<li>15 multi-language alphabet packs — pick a script from the dropdown, the freeform Local Alphabet field is overwritten on save.</li>
<li>Appearance toggles — Horizontal / Vertical layout, Uppercase / Lowercase letter case, Disable Empty Letters (renders empty buckets as muted + <code>aria-disabled</code>), Hide Pagination If One Page.</li>
<li>Generic taxonomy filter — restrict the index to any registered taxonomy + term (beyond the legacy cat/tag args).</li>
<li>Meta-key intra-bucket sorting — set a post meta key + ASC / DESC to override post_title ordering within each letter bucket. Buckets still derive from post_title.</li>
<li>Per-page override map — <code>{ post_id => items_per_page }</code> so /glossary can render 50 items per page while /products renders 20.</li>
<li>DOM auto-injection — for themes that don’t expose a hook: render the index in the footer and move it into a CSS selector via ~300 bytes of vanilla JS. No jQuery.</li>
</ul>
<h4>Backwards compatibility</h4>
<ul>
<li>The legacy <code>wp_snap()</code> template tag is preserved as a thin alias.</li>
<li>Legacy URL parameters <code>?snap=</code>, <code>?cp=</code>, and <code>?snap_paged=</code> continue to be honoured alongside the canonical <code>?alpha_order=</code> and <code>?alpha_paged=</code>.</li>
<li>Legacy <code>key_snap_*</code> option keys are migrated to <code>wp_snap_ext_*</code> automatically on activation.</li>
</ul>
<h3>Usage</h3>
<h4>Gutenberg block</h4>
Add the Alphabetical Pagination block from the block inserter (Widgets category) and configure attributes through the block sidebar:
<ul>
<li><code>postType</code> — post type to index (default <code>post</code>).</li>
<li><code>menu</code> — <code>1</code>, <code>2</code>, or <code>3</code> (see menu styles in the admin panel).</li>
<li><code>firstload</code> — <code>all</code>, <code>none</code>, or <code>recent</code>.</li>
<li><code>category</code> — category ID or <code>all</code>.</li>
<li><code>includeChildren</code> — include category children.</li>
<li><code>taxonomy</code> + <code>term</code> — restrict the index to a specific term of any registered taxonomy.</li>
<li><code>display</code> — <code>true</code> (default) renders the post list under the letter nav; <code>false</code> renders only the letter nav.</li>
</ul>
The block is fully server-rendered — its HTML matches the shortcode and template tag output byte for byte, and there is no JS build pipeline behind it.
<h4>Shortcode</h4>
Drop the shortcode into any post, page, widget, or Site Editor template part:
<pre><code>[alphabetical_pagination]
</code></pre>
All template-tag arguments are exposed as shortcode attributes:
<pre><code>[alphabetical_pagination cat="15" child="true" menu="2" firstload="recent" post_type="post" display="true"]
</code></pre>
Attribute reference:
<ul>
<li><code>cat</code> — category ID, or <code>all</code>.</li>
<li><code>child</code> — <code>true</code> to include category children (default <code>false</code>).</li>
<li><code>menu</code> — 1, 2 or 3 (see menu styles in the admin panel).</li>
<li><code>firstload</code> — <code>all</code>, <code>none</code> or <code>recent</code>.</li>
<li><code>post_parent</code> — restrict to posts with a given parent ID.</li>
<li><code>post_type</code> — defaults to <code>post</code>. Whitelisted against registered post types.</li>
<li><code>display</code> — <code>true</code> (default) renders the post list under the letter nav; <code>false</code> renders only the letter nav.</li>
</ul>
The shortcode handler buffers its output through <code>ob_start()</code> / <code>ob_get_clean()</code>, so the index renders exactly where you place the shortcode rather than breaking out of the surrounding layout.
<h4>Theme template tag</h4>
For deeper theme integration, call <code>alphabetical_pagination()</code> directly from a template file. The legacy <code>wp_snap()</code> name is retained as a backwards-compatible alias.
<pre><code><?php
if ( function_exists( 'alphabetical_pagination' ) ) {
 echo alphabetical_pagination();
}
?>
</code></pre>
Passing arguments works the same as the original <code>wp_snap()</code> API:
<pre><code><?php
echo alphabetical_pagination( 'cat=15&child=true&firstload=recent' );
?>
</code></pre>
Render an alphabetical index over a custom post type:
<pre><code><?php
echo alphabetical_pagination( '', 'glossary_term' );
?>
</code></pre>
Render only the letter navigation (without the post list):
<pre><code><?php
echo alphabetical_pagination( '', 'post', false );
?>
</code></pre>
<h4>URL query parameters</h4>
Once embedded, the plugin reads two query parameters on the front end:
<ul>
<li><code>?alpha_order=A</code> — the active letter (or bucket, like <code>A-D</code>). <code>alpha_order=misc</code> selects the <code>#</code> bucket of non-alphanumeric titles.</li>
<li><code>?alpha_paged=2</code> — the active pagination page.</li>
</ul>
These are isolated to the plugin (they do not collide with WordPress’s own <code>paged</code> / <code>tag</code> / <code>cat</code> query vars). The legacy <code>?snap=</code> / <code>?cp=</code> parameters from earlier versions are still accepted so existing bookmarks keep working.
<h4>Gutenberg block attributes</h4>
 Attribute 
 Type 
 Default 
 Notes
 <code>postType</code> 
 string 
 <code>post</code> 
 Any registered public post type.
 <code>menu</code> 
 number 
 <code>1</code> 
 1, 2, or 3.
 <code>firstload</code> 
 string 
 <code>recent</code> 
 <code>all</code> / <code>none</code> / <code>recent</code>.
 <code>category</code> 
 string 
 “ 
 Category ID or <code>all</code>.
 <code>includeChildren</code> 
 boolean 
 <code>false</code> 
 Include category children.
 <code>taxonomy</code> 
 string 
 “ 
 Any registered taxonomy slug.
 <code>term</code> 
 number 
 <code>0</code> 
 Term ID for the taxonomy above.
 <code>display</code> 
 boolean 
 <code>true</code> 
 Render the post list under the nav.
The block supports <code>wide</code> and <code>full</code> alignment via the <code>supports.align</code> declaration in <code>block.json</code>.
<h4>REST API</h4>
Two read-only public routes under <code>/wp-json/wp-snap-ext/v1/</code>:
<code>GET /letters</code>
Query params: <code>post_type</code> (default <code>post</code>), <code>taxonomy</code>, <code>term</code>.
Response (200 OK):
<pre><code>[ { "letter": "A", "count": 12, "href": "https://example.com/?alpha_order=A" }, … ]
</code></pre>
<code>GET /posts</code>
Query params: <code>post_type</code>, <code>taxonomy</code>, <code>term</code>, <code>letter</code> (single character or <code>#</code>), <code>page</code> (default 1), <code>per_page</code> (default 10, max 100).
Response (200 OK):
<pre><code>{ "posts": [ { "id": 42, "title": "...", "permalink": "...", "excerpt": "..." } ], "total": 75, "total_pages": 8, "page": 1, "per_page": 10 }
</code></pre>
Toggle the endpoints on / off under Settings → Alphabetical Pagination → REST API & Cache. Lockdown plugins that block public REST surface should leave the toggle off.
<h4>WooCommerce auto-mount</h4>
Enable Settings → Alphabetical Pagination → WooCommerce → Auto-mount on Shop. The index renders above the shop loop (or after the archive description / before main content — pick the mount hook from the dropdown) on:
<ul>
<li>the WooCommerce shop archive,</li>
<li>product taxonomy archives (e.g. <code>/product-category/food</code>).</li>
</ul>
The mount uses native WooCommerce actions, never <code>posts_where</code>, so it does not collide with caching plugins, SEO plugins, or multilingual plugins that also filter WP_Query.
<h4>Developer hooks</h4>
Customise behaviour without forking through the following hooks (added in 2.3.0):
<pre><code>add_filter( 'wp_snap_ext/query_args', function( $args, $context ) {
 $args['meta_query'] = [ [ 'key' => 'featured', 'value' => '1' ] ];
 return $args;
}, 10, 2 );

add_filter( 'wp_snap_ext/letter_href', function( $href, $letter, $base ) {
 return str_replace( '?alpha_order=', '#letter/', $href );
}, 10, 3 );

add_filter( 'wp_snap_ext/excerpt', function( $excerpt, $post_id ) {
 return wp_trim_words( $excerpt, 25, '…' );
}, 10, 2 );
</code></pre>
Full list:
<ul>
<li><code>do_action( 'wp_snap_ext/before_render', $context )</code> — fires before the index renders.</li>
<li><code>apply_filters( 'wp_snap_ext/pre_render', $html, $post_type, $display, $args )</code> — short-circuit; return a string to replace the HTML.</li>
<li><code>apply_filters( 'wp_snap_ext/query_args', $args, $context )</code> — mutate WP_Query arguments.</li>
<li><code>apply_filters( 'wp_snap_ext/letter_href', $href, $letter, $base )</code> — rewrite letter link hrefs (router compatibility).</li>
<li><code>apply_filters( 'wp_snap_ext/excerpt', $excerpt, $post_id )</code> — post-process the resolved excerpt.</li>
<li><code>apply_filters( 'wp_snap_ext/render', $html, $post_type, $display, $args )</code> — final filter on rendered HTML.</li>
<li><code>do_action( 'wp_snap_ext/after_render', $html, $context )</code> — fires after the index has rendered.</li>
</ul>
<h4>Backend settings</h4>
Under Settings → Alphabetical Pagination you’ll find:
<ul>
<li>Navigational Menu Options — Local Alphabet, Menu Style, Group Posts, Recent Posts, CSS class names, Ignore When Alphabetizing.</li>
<li>Presentational Options — Fancy URLs, Fancy URL Name, Tabs.</li>
<li>Pagination → Items Per Page — integer, defaults to 10. Registered through the WordPress Settings API and sanitised with <code>absint()</code>.</li>
<li>Content Fallback → ACF Excerpt Fallback — checkbox. When on, posts without a native WordPress excerpt fall back to the value of an ACF field instead of the trimmed post content. ACF lookup chain: <code>get_field()</code> → <code>get_sub_field()</code> → recursive <code>get_fields()</code> walk for deeply nested flexible-content / repeater / group sub-fields.</li>
<li>Content Fallback → ACF Field Name — the field name (or key) read by <code>get_field()</code> when the toggle is enabled. The plugin gracefully no-ops if ACF (or ACF Pro) is not installed.</li>
<li>Appearance → Layout — Horizontal or Vertical letter strip.</li>
<li>Appearance → Letter Case — Uppercase or Lowercase.</li>
<li>Appearance → Disable Empty Letters — renders empty buckets as muted + <code>aria-disabled</code>, with the anchor stripped.</li>
<li>Appearance → Hide Pagination If One Page — skips the Previous/Next strip when the filtered set fits on one page.</li>
<li>Language → Alphabet Pack — pick from 15 bundled scripts. Selecting a pack overwrites the freeform Local Alphabet field on save.</li>
<li>Sorting → Meta Key — post meta key used for intra-bucket ordering instead of post_title.</li>
<li>Sorting → Meta Order — ASC / DESC.</li>
<li>Taxonomy Filter → Taxonomy + Term ID — restrict the index to a single term of any registered taxonomy.</li>
<li>WooCommerce → Auto-mount on Shop + Mount Hook — see the WooCommerce section above.</li>
<li>DOM Injection → Enable DOM Injection + Target Selector — print the index in the footer and move it into a CSS selector via vanilla JS.</li>
<li>REST API & Cache → Enable REST Endpoints + Cache TTL — see the REST API section above.</li>
</ul>

Alternatives to Alphabetical Pagination

Top alternatives