Category Labels Block

Show a post’s categories or tags as linked labels.

Lauren Gray Avatar

Category Labels Block shows a post’s categories or tags as linked labels. You pick the terms you want, and by default each label only appears on posts that actually have that term. If you use Yoast SEO or Rank Math, you can also show the post’s primary category.

Before you start

  • WordPress 5.8.3 or later
  • PHP 5.6 or later
  • Optional: Yoast SEO or Rank Math, if you want to use the Primary Term block. That block only shows up when one of them is active.

Install

  1. In your WordPress dashboard, go to Plugins → Add New Plugin.
  2. Click Upload Plugin.
  3. Choose the plugin zip file.
  4. Click Install Now.
  5. Click Activate.

How to use

The plugin is a small family of blocks that nest inside each other:

  • Category Labels is the container. It holds your labels and controls which ones show.
  • Post Term is one linked label for one category or tag. It only works inside Category Labels.
  • Primary Term is a linked label for the post’s primary category from Yoast SEO or Rank Math. It only works inside Category Labels.
  • Term Name is the label text. It sits inside Post Term or Primary Term and is added for you.

Add labels to a post or template

  1. Open a post, page or template in the block editor.
  2. Click the + inserter and add the Category Labels block.
  3. Inside it, add a Post Term block.
  4. Click the new label. A search box (Search Terms) opens. Type to find a category or tag and select it.
  5. Optional: turn on Open in new Tab in the same popover if you want the label link to open in a new tab.
  6. Repeat for each term you want as a label. The order of your Post Term blocks is the order the labels appear.
  7. Style the labels with the usual block tools in the sidebar: color, typography, spacing and border.

To change a label’s term later, select the Post Term block and click Edit Category in the block toolbar.

With Scope to current post on (the default), a label only shows on posts that have that term. So you can add every label you might need, drop the block into a single post template, and each post only shows the ones that apply. If none of the labels match a post, the block outputs nothing at all, not even an empty wrapper.

Show the primary category

  1. Make sure Yoast SEO or Rank Math is active and that your posts have a primary category set there.
  2. Inside a Category Labels block, add a Primary Term block. In the editor it reads “Primary term” as a stand-in.
  3. On the front end, it shows the post’s primary category, linked to that category’s archive.
  4. Optional: turn on Fallback in the block sidebar to show the top-most parent of the primary category instead.

If the post has no primary category, the Primary Term block shows nothing.

Convert a Post Terms block

Already using the core Post Terms block? Select it and use the block toolbar’s transform menu to turn it into Category Labels. You get one Post Term label for each category assigned to the post you’re editing. This option only appears when that post has at least one category.

Block options

Category Labels

  • Scope to current post: shows only the labels whose term is assigned to the current post. Default: on. Turn it off to show every label you added, on every post.
  • Limit Categories (Pro): the maximum number of labels to show, counted in the order they appear in the block. Only shows when Scope to current post is on. Default: empty (no limit).
  • Layout, color (background and link), typography, spacing and wide/full alignment come from the standard block tools.

Post Term

  • Search Terms: pick the category or tag this label links to.
  • Open in new Tab: opens the label link in a new tab. Default: off.

Primary Term

  • Fallback (in the General panel): “Displays the top-most parent category of the post’s primary category (if exists).” Default: off.

What Pro adds

  • Any taxonomy. The free version’s term search covers categories and tags. Pro searches all terms, including custom taxonomies.
  • Limit Categories. Cap how many labels show per post.
  • Term Abbreviation block. A short, editable text badge (it shows “?” until you type something) that you can add inside a Post Term or Primary Term label alongside the name. Use the inserter button that Pro adds to the label’s block toolbar to add it.

Developer reference

For developers: hooks and functions you can use from your theme or a code snippet.

clb_get_primary_term( $post_id = null )

Function. Returns the post’s primary category as a WP_Term, using Yoast SEO or Rank Math, or false if there isn’t one. Defaults to the current post.

$term = function_exists( 'clb_get_primary_term' ) ? clb_get_primary_term() : false;

if ( $term ) {
	printf( '<a href="%s">%s</a>', esc_url( get_term_link( $term ) ), esc_html( $term->name ) );
}

clb_get_active_seo_plugin()

Function. Returns 'yoast', 'rank-math' or false, depending on which SEO plugin the primary category comes from.

FAQs

Is there a limit to how many categories I can show?

No. In the free version, every label that matches the post shows. Pro adds Limit Categories if you want to cap it.

Where did the primary category toggles go?

They moved into their own block. Add a Primary Term block inside Category Labels instead. The Category Labels sidebar shows a tip saying the same thing.

Why don’t I see the Primary Term block?

It’s only offered when Yoast SEO or Rank Math is active.