Set a primary category or term for any taxonomy

When a post belongs to several categories, or to several terms of the same taxonomy, the primary term tells SEOPress which one to use in your permalinks, dynamic variables and breadcrumbs.

Since SEOPress 10.4, you can set a primary term on every public, hierarchical taxonomy shown in the WordPress admin: categories, WooCommerce product categories, and your own hierarchical taxonomies (for example a “Genre” taxonomy for books, or a “Location” taxonomy for services). Before 10.4, only categories and product categories offered one.

What the primary term is used for

• Permalinks: the primary category replaces the first category in the %category% permalink tag of your posts, and the primary product category is used in WooCommerce product permalinks that include the product category. The primary term of other taxonomies does not change your permalinks.
• Dynamic variables: %%post_category%% returns the primary category, and %%_ct_<taxonomy>%% (e.g. %%_ct_genre%%) the primary term of that taxonomy, in your titles, meta descriptions, social tags and schemas. See the list of dynamic variables.
• Breadcrumbs (SEOPress PRO): when a taxonomy is selected for a post type in SEO > PRO > Breadcrumbs > Taxonomy to show in Breadcrumbs, the trail goes through the primary term of that taxonomy and its parents.

Without a primary term, SEOPress uses the first term attached to the post, as WordPress does. If you remove the primary term from the post (for example by unchecking it), SEOPress ignores it and falls back to the first term.

Set the primary term of a post

The selector lists only the terms assigned to the post. Assign at least one term first, then choose the primary one. Select None (will disable this feature) to remove the primary term.

In the block editor

1. Edit your post and open the Settings sidebar.
2. In the panel of the taxonomy (Categories, Product categories or your own taxonomy), check the terms of the post.
3. Below the list of terms, choose the primary one in Select a primary category (or Select a primary followed by the name of your taxonomy, e.g. Select a primary Genre).
4. Save the post.

In the Classic Editor

The same selector is added at the bottom of the taxonomy box (Categories, Product categories or your own taxonomy). Its list follows the boxes you check or uncheck. Choose the primary term, then click Update or Publish.

In the SEO metabox

In the Advanced tab of the SEO metabox, you will find one selector per taxonomy, with the same label. This tab always offers the selector, even when it is hidden from the taxonomy box (see the seopress_primary_term_inline_selector filter below).

How the primary term is stored

The primary term is saved as a post meta holding the term ID:

These keys are available in the WordPress REST API (meta field of the post). With WPML, the primary term is copied to the translations and converted to the translated term. When you import your data from Yoast SEO, the primary term of each taxonomy is imported too.

To read the primary term in your own code:

// Primary term of the "genre" taxonomy, as a term ID (empty string if none).
$term_id = get_post_meta( get_the_ID(), '_seopress_robots_primary_term_genre', true );
if ( $term_id && has_term( (int) $term_id, 'genre' ) ) {
	$term = get_term( (int) $term_id, 'genre' );
}

Before SEOPress 10.4, some sites stored the term of another taxonomy in _seopress_robots_primary_cat (CSV import, REST API, or the seopress_primary_category_list filter). SEOPress keeps reading that value for the taxonomy until you save a primary term for it.

For developers: filters

Add these snippets to the functions.php file of your child theme or to a must-use plugin.

Choose the taxonomies that offer a primary term

The seopress_primary_term_taxonomies filter receives the taxonomies offering a selector (an array of WP_Taxonomy objects keyed by name) and the post type. Remove a taxonomy:

add_filter( 'seopress_primary_term_taxonomies', function( $taxonomies, $post_type ) {
	unset( $taxonomies['genre'] );
	return $taxonomies;
}, 10, 2 );

Or add a non-hierarchical taxonomy, such as tags on posts. Its selector is offered in the Advanced tab of the SEO metabox:

add_filter( 'seopress_primary_term_taxonomies', function( $taxonomies, $post_type ) {
	if ( 'post' === $post_type ) {
		$taxonomies['post_tag'] = get_taxonomy( 'post_tag' );
	}
	return $taxonomies;
}, 10, 2 );

Filter the terms offered

The seopress_primary_term_list filter receives the terms offered, the taxonomy name and the post. For example, never offer “Uncategorized”:

add_filter( 'seopress_primary_term_list', function( $terms, $taxonomy, $post ) {
	if ( 'category' !== $taxonomy || ! is_array( $terms ) ) {
		return $terms;
	}
	return array_values(
		array_filter( $terms, function( $term ) {
			return 'uncategorized' !== $term->slug;
		} )
	);
}, 10, 3 );

The older seopress_primary_category_list filter still runs, for categories and product categories only. It receives the terms alone.

Hide the selector from the taxonomy box

Return false from the seopress_primary_term_inline_selector filter to remove the selector from the taxonomy box of the block editor and the Classic Editor. It receives the current value, the taxonomy name and the post type. A primary term already saved keeps working, and the Advanced tab of the SEO metabox still offers the selector.

add_filter( 'seopress_primary_term_inline_selector', function( $enabled, $taxonomy, $post_type ) {
	if ( 'product_cat' === $taxonomy ) {
		return false;
	}
	return $enabled;
}, 10, 3 );

Learn more on our hook page: hide the primary category dropdown on the post edit screen.