Title: wp_unique_term_slug
Published: April 25, 2014
Last modified: February 24, 2026

---

# wp_unique_term_slug( string $slug, object $term ): string

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#wp--skip-link--target)

Makes term slug unique, if it isn’t already.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#description)󠁿

The `$slug` has to be unique global to every taxonomy, meaning that one taxonomy
term can’t have a matching slug with another taxonomy term. Each slug has to be 
globally unique for every taxonomy.

The way this works is that if the taxonomy that the term belongs to is hierarchical
and has a parent, it will append that parent to the $slug.

If that still doesn’t return a unique slug, then it tries to append a number until
it finds a number that is truly unique.

The only purpose for `$term` is for appending a parent, if one exists.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#parameters)󠁿

 `$slug`stringrequired

The string that will be tried for a unique slug.

`$term`objectrequired

The term object that the `$slug` will belong to.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#return)󠁿

 string Will return a true unique slug.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#source)󠁿

    ```php
    function wp_unique_term_slug( $slug, $term ) {
    	global $wpdb;

    	$needs_suffix  = true;
    	$original_slug = $slug;

    	// As of 4.1, duplicate slugs are allowed as long as they're in different taxonomies.
    	if ( ! term_exists( $slug ) || get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
    		$needs_suffix = false;
    	}

    	/*
    	 * If the taxonomy supports hierarchy and the term has a parent, make the slug unique
    	 * by incorporating parent slugs.
    	 */
    	$parent_suffix = '';
    	if ( $needs_suffix && is_taxonomy_hierarchical( $term->taxonomy ) && ! empty( $term->parent ) ) {
    		$the_parent = $term->parent;
    		while ( ! empty( $the_parent ) ) {
    			$parent_term = get_term( $the_parent, $term->taxonomy );
    			if ( is_wp_error( $parent_term ) || empty( $parent_term ) ) {
    				break;
    			}
    			$parent_suffix .= '-' . $parent_term->slug;
    			if ( ! term_exists( $slug . $parent_suffix ) ) {
    				break;
    			}

    			if ( empty( $parent_term->parent ) ) {
    				break;
    			}
    			$the_parent = $parent_term->parent;
    		}
    	}

    	// If we didn't get a unique slug, try appending a number to make it unique.

    	/**
    	 * Filters whether the proposed unique term slug is bad.
    	 *
    	 * @since 4.3.0
    	 *
    	 * @param bool   $needs_suffix Whether the slug needs to be made unique with a suffix.
    	 * @param string $slug         The slug.
    	 * @param object $term         Term object.
    	 */
    	if ( apply_filters( 'wp_unique_term_slug_is_bad_slug', $needs_suffix, $slug, $term ) ) {
    		if ( $parent_suffix ) {
    			$slug .= $parent_suffix;
    		}

    		if ( ! empty( $term->term_id ) ) {
    			$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
    		} else {
    			$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
    		}

    		if ( $wpdb->get_var( $query ) ) { // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
    			$num = 2;
    			do {
    				$alt_slug = $slug . "-$num";
    				++$num;
    				$slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
    			} while ( $slug_check );
    			$slug = $alt_slug;
    		}
    	}

    	/**
    	 * Filters the unique term slug.
    	 *
    	 * @since 4.3.0
    	 *
    	 * @param string $slug          Unique term slug.
    	 * @param object $term          Term object.
    	 * @param string $original_slug Slug originally passed to the function for testing.
    	 */
    	return apply_filters( 'wp_unique_term_slug', $slug, $term, $original_slug );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/taxonomy.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/taxonomy.php#L3101)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/taxonomy.php#L3101-L3179)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#hooks)󠁿

 [apply_filters( ‘wp_unique_term_slug’, string $slug, object $term, string $original_slug )](https://developer.wordpress.org/reference/hooks/wp_unique_term_slug/)

Filters the unique term slug.

 [apply_filters( ‘wp_unique_term_slug_is_bad_slug’, bool $needs_suffix, string $slug, object $term )](https://developer.wordpress.org/reference/hooks/wp_unique_term_slug_is_bad_slug/)

Filters whether the proposed unique term slug is bad.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#related)󠁿

| Uses | Description | 
| [term_exists()](https://developer.wordpress.org/reference/functions/term_exists/)`wp-includes/taxonomy.php` |

Determines whether a taxonomy term exists.

  | 
| [get_term_by()](https://developer.wordpress.org/reference/functions/get_term_by/)`wp-includes/taxonomy.php` |

Gets all term data from database by term field and data.

  | 
| [is_taxonomy_hierarchical()](https://developer.wordpress.org/reference/functions/is_taxonomy_hierarchical/)`wp-includes/taxonomy.php` |

Determines whether the taxonomy object is hierarchical.

  | 
| [get_term()](https://developer.wordpress.org/reference/functions/get_term/)`wp-includes/taxonomy.php` |

Gets all term data from database by term ID.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [get_option()](https://developer.wordpress.org/reference/functions/get_option/)`wp-includes/option.php` |

Retrieves an option value based on an option name.

  | 
| [wpdb::get_var()](https://developer.wordpress.org/reference/classes/wpdb/get_var/)`wp-includes/class-wpdb.php` |

Retrieves one value from the database.

  | 
| [wpdb::prepare()](https://developer.wordpress.org/reference/classes/wpdb/prepare/)`wp-includes/class-wpdb.php` |

Prepares a SQL query for safe execution.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  |

[Show 6 more](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#)

| Used by | Description | 
| [wp_update_term()](https://developer.wordpress.org/reference/functions/wp_update_term/)`wp-includes/taxonomy.php` |

Updates term based on arguments provided.

  | 
| [wp_insert_term()](https://developer.wordpress.org/reference/functions/wp_insert_term/)`wp-includes/taxonomy.php` |

Adds a new term to the database.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/?output_format=md#changelog)󠁿

| Version | Description | 
| [2.3.0](https://developer.wordpress.org/reference/since/2.3.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_unique_term_slug%2F)
before being able to contribute a note or feedback.