Generating unique term slugs in WordPress with wp_unique_term_slug

The wp_unique_term_slug function in WordPress is primarily designed to generate a unique slug for a term. This function is part of the WordPress core and is typically used when creating or updating a term in a taxonomy. The function ensures that the slug generated for a term is unique, even if the term is in a hierarchical taxonomy.

From a functionality perspective, the wp_unique_term_slug function is designed to prevent conflicts between slugs. It does this by appending a numeric suffix to the slug in cases where a term with the same slug already exists within the same taxonomy. This prevents potential errors or issues that could arise from having duplicate slugs.

For instance, if a term named ‘Apple’ exists in a ‘Fruit’ taxonomy and another term named ‘Apple’ is created in the same taxonomy, the wp_unique_term_slug function ensures that the second ‘Apple’ term is assigned a unique slug (like ‘apple-2’) to prevent any conflicts.

The wp_unique_term_slug function is a part of the WordPress Term API and is typically used in conjunction with other functions that create or modify terms in taxonomies.

Parameters Accepted by wp_unique_term_slug Function

The WordPress wp_unique_term_slug function accepts two parameters:

  • $slug (string): This is a required parameter. It signifies the string that will be tested to generate a unique slug.
  • $term (object): This is also a required parameter. It represents the term object to which the $slug will be associated.

Return Value of wp_unique_term_slug Function

The wp_unique_term_slug function will return a string that is a truly unique slug.

If the function does not accept any parameters, it will be explicitly stated.


How to Generate a Unique Slug for a New Term

$term_name = 'New Term';
$term_slug = sanitize_title($term_name);
$term = get_term_by('name', $term_name, 'category');

if ($term === false) {
 $unique_slug = wp_unique_term_slug($term_slug, (object) array('parent' => 0));
} else {
 $unique_slug = wp_unique_term_slug($term_slug, $term);

echo '<p>The unique slug for the term is: ' . $unique_slug . '</p>';

In this example, we’re generating a unique slug for a new term. We first sanitize the term name to create a slug. Then we check if the term already exists. If it doesn’t exist, we generate a unique slug with a parent of 0. If it does exist, we generate a unique slug using the existing term object. The unique slug is then output in a paragraph.

How to Check if a Slug is Unique for a Term

$slug = 'test-slug'; // Replace with your slug
$term = get_term_by('slug', $slug, 'category');

if ($term === false) {
 echo '<p>The slug is unique.</p>';
} else {
 $unique_slug = wp_unique_term_slug($slug, $term);
 echo '<p>The unique slug for the term is: ' . $unique_slug . '</p>';

In this example, we’re checking if a slug is unique for a term. We first get the term by the slug. If the term doesn’t exist, we output a message saying the slug is unique. If the term does exist, we generate a unique slug and output it in a paragraph.


The WordPress wp_unique_term_slug function plays a significant role in ensuring the uniqueness of term slugs in the database. It is particularly beneficial when you’re adding new terms and need to avoid duplication. The function achieves this by appending a number to the end of duplicate slugs, thus preserving the integrity of your data and preventing potential conflicts. Therefore, understanding and properly implementing the wp_unique_term_slug function can aid in maintaining a well-structured and error-free term database in your WordPress development projects.

Related WordPress Functions