Primary category in WordPress: permalinks, breadcrumbs and schema

A WordPress post can sit in several categories, but some places have room for only one: the category in the post's URL, the breadcrumb trail, the section named in its schema. WordPress picks that one by a rule you cannot see in the editor. From version 0.0.30, Hydrogen SEO adds a Primary Category choice to the editor's own Categories panel, and uses your choice everywhere a single category has to stand for the post. It is free and needs no account.

Choose the primary category

In the block editor

Open the post and find Categories in the settings sidebar.
Tick two or more categories. A Primary Category dropdown appears under the checklist, with the note Used in breadcrumbs, schema and permalinks. It starts at Not set.
Pick the category that best describes the post. Nothing is chosen until you do.
Save or update the post. The choice is saved with it.

The dropdown lists only the categories that are ticked. With a single category ticked there is nothing to choose, so it stays hidden.

In the Classic editor

The same dropdown sits under the Categories box on the edit screen. Its options follow the boxes you tick, and it is saved when you click Update or Publish.

WooCommerce products

Products get a matching dropdown for product categories, in the Product categories panel or box. It behaves the same way.

What the choice changes

Place	With a primary category	Without one
Post URL, when the permalink structure contains `%category%`	The primary category (and its parents)	WordPress's default: the category with the lowest ID
Breadcrumbs and BreadcrumbList schema	The trail goes through the primary category	The most specific category the post is in
`articleSection` in Article schema	The primary category's name	The first category WordPress returns
`%category%` in title, description and schema template variables	The primary category's name	The first category WordPress returns
WooCommerce product URL, when the product permalink contains `%product_cat%`	The primary product category	WooCommerce's default
WooCommerce's own breadcrumb on a product	The primary product category	WooCommerce's default

A post with no primary category stored keeps every one of these exactly as it was. One case needs a look when you update: posts that already have a primary category stored, for example from an import, start using it in their permalinks. That is covered under posts that already had a primary category below.

Before you change it on a published post

Check Settings → Permalinks first. If your structure does not contain %category%, choosing a primary category never changes a URL, only breadcrumbs, schema and the %category% variable.

If it does contain %category%, changing the primary category of a published post changes that post's address. The old address is not redirected. It keeps loading the post with a normal 200 response, and its canonical tag points to the new address. WordPress redirects a category permalink only when the post is not in the category named in the URL, and the post is still in its old category. So:

Links inside your own posts keep pointing at the old address until you edit them. They work, but they lead to a second copy of the post.
Search engines learn the new address from the canonical tag. That takes time, and a canonical tag is a strong hint, not an instruction.
If the old address has to redirect, add a 301 for it in the redirection manager.
A page cache can keep serving the old copy with its old canonical tag, so open the old address once and check the canonical in the page source.

The safest habit is to choose the primary category before a post is first published. For an established post, change it when the current category is plainly wrong, not to tidy up.

Rules the picker follows

Only an assigned category can be primary. If the primary category is later unticked, in the editor, Quick Edit, Bulk Edit or through code, the stored choice is removed when the post is saved.
The picker never chooses for you. With no primary category chosen, the dropdown stays at Not set however many categories you tick or untick. If you untick the category that was primary, the dropdown goes back to Not set. It does not move to another category.
Opening a post changes nothing. The editor writes a value only after you tick, untick or choose, so a post you only looked at is not marked as edited.
Not set is shown for a post with several categories and no stored choice. Until you pick one, the post behaves as it did before.

Posts that already had a primary category

Earlier versions could already store a primary category for a post, through Import SEO Data or Hydrogen AI, and used it for breadcrumbs. From 0.0.30 those posts use it in %category% permalinks as well, and products in %product_cat% permalinks. On a site with such posts and a category permalink structure, some addresses therefore change when you update. The old addresses keep loading, each with a canonical tag pointing to the new one.

If those addresses must stay as they are, switch the permalink effect off with the hydrogen_seo_primary_term_in_permalinks filter, shown under For developers. Breadcrumbs, schema and the %category% variable keep using the primary category either way.

Which post types get the picker

Any post type that uses the standard Category taxonomy, plus WooCommerce products for product categories. Tags and custom taxonomies have no primary term.

In the block editor the picker also needs the post type to support custom fields and the taxonomy to be available to the REST API, which is true for posts and for WooCommerce products. In the Classic editor it only needs the taxonomy's box to be shown.

Coming from another SEO plugin

Tools → Import SEO Data brings primary categories across from Yoast SEO, Rank Math and SEOPress, for posts and for products. After the import, the editor shows the imported choice in the same dropdown, and on a %category% permalink structure the imported choice is used in the post's address. A primary term chosen in All in One SEO is not copied; the import report lists it. See switch from another SEO plugin.

With Hydrogen AI

Hydrogen AI can set a post's primary category on request, for example "make Recipes the primary category of every post that is in both Recipes and News". As with its other changes, it lists the posts before anything is written.

For developers

The choice is stored as post meta: hydrogen_seo_post_meta_primary_category for categories and hydrogen_seo_post_meta_primary_product_cat for product categories. Each holds a term ID, is available in the REST API under the post's meta, and can be written by anyone who may edit the post. The keys are protected, so they do not appear in the Custom Fields box.

A stored ID counts only while that term is assigned to the post. Code that sets the meta directly should assign the term first.

The hydrogen_seo_primary_term_in_permalinks filter decides whether the primary term is used in permalinks. It receives a boolean, true by default, and the post, and is asked only for posts that have a valid primary term. Return false to keep the category WordPress or WooCommerce picks for the address:

php

// Keep existing post addresses. Breadcrumbs, schema and %category% still use the primary category.
add_filter( 'hydrogen_seo_primary_term_in_permalinks', '__return_false' );

It is listed in the filters reference.

Performance

Reading the primary category adds no database query: the post's categories and its meta are already in WordPress's caches when a page is built, and a post with fewer than two categories skips the check entirely.

FAQ

Does the primary category change which archives the post appears in?

No. The post stays in every category it is assigned to and is listed in each category's archive. The primary category only decides which one represents the post where a single one is needed.

Will setting it change my URLs?

Only if your permalink structure contains %category% (or %product_cat% for products), and only for posts in more than one category where the primary differs from the one WordPress had been using.

Does the old address redirect after I change the primary category?

No. While the post is still in its old category, the old address loads the post as before and carries a canonical tag pointing to the new address. WordPress redirects it only once the post is no longer in that category. Add a 301 in the redirection manager if you need one.

Can the picker change my primary category without me?

No. It never sets one. It only clears the choice, back to Not set, when the category that was primary is removed from the post.

The post has fewer than two categories ticked, or the post type does not use categories. In the block editor, a custom post type also needs custom-fields support for the dropdown to appear.

Does Google rank the primary category higher?

There is no such signal. The benefit is consistency: the URL, the breadcrumb in search results and the schema all name the same section, and it is the section you chose.

Can a tag be primary?

No. Only categories and WooCommerce product categories.