Title: add_rewrite_tag
Published: April 25, 2014
Last modified: May 20, 2026

---

# add_rewrite_tag( string $tag, string $regex, string $query = '' )

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#parameters)
 * [More Information](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#more-information)
 * [What it does](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#what-it-does)
 * [Source](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#user-contributed-notes)

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

Adds a new rewrite tag (like %postname%).

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

The `$query` parameter is optional. If it is omitted you must ensure that you call
this on, or before, the [‘init’](https://developer.wordpress.org/reference/hooks/init/)
hook. This is because `$query` defaults to `$tag=`, and for this to work a new query
var has to be added.

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

 `$tag`stringrequired

Name of the new rewrite tag.

`$regex`stringrequired

Regular expression to substitute the tag for in rewrite rules.

`$query`stringoptional

String to append to the rewritten query. Must end in `'='`.

Default:`''`

## 󠀁[More Information](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#more-information)󠁿

This function can be used to make WordPress aware of custom querystring variables.
Generally, it’s used in combination with [add_rewrite_rule()](https://developer.wordpress.org/reference/functions/add_rewrite_rule/)
to create rewrite rules for pages with custom templates.

If you use this function to declare a rewrite tag that already exists, the existing
tag will be _overwritten_.

This function _must_ be called on [init](https://developer.wordpress.org/reference/hooks/init/)
or earlier.

## 󠀁[What it does](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#what-it-does)󠁿

 * Gets a query var name by stripping the % signs from the name of the tag: trim(
   $tag, ‘%’)
 * Calls $[wp_rewrite::add_rewrite_tag()](https://developer.wordpress.org/reference/classes/wp_rewrite/add_rewrite_tag/)
   with the name, generated QV name and regex.
 * Adds the QV as a query var (again, this could be done by filtering query_vars
   but it might be nicer to add a function to the WP class that stores ‘extra’ QVs
   like above)

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

    ```php
    function add_rewrite_tag( $tag, $regex, $query = '' ) {
    	// Validate the tag's name.
    	if ( strlen( $tag ) < 3 || '%' !== $tag[0] || '%' !== $tag[ strlen( $tag ) - 1 ] ) {
    		return;
    	}

    	global $wp_rewrite, $wp;

    	if ( empty( $query ) ) {
    		$qv = trim( $tag, '%' );
    		$wp->add_query_var( $qv );
    		$query = $qv . '=';
    	}

    	$wp_rewrite->add_rewrite_tag( $tag, $regex, $query );
    }
    ```

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

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

| Uses | Description | 
| [WP::add_query_var()](https://developer.wordpress.org/reference/classes/wp/add_query_var/)`wp-includes/class-wp.php` |

Adds a query variable to the list of public query variables.

  | 
| [WP_Rewrite::add_rewrite_tag()](https://developer.wordpress.org/reference/classes/wp_rewrite/add_rewrite_tag/)`wp-includes/class-wp-rewrite.php` |

Adds or updates existing rewrite tags (e.g. %postname%).

  |

| Used by | Description | 
| [WP_Sitemaps::register_rewrites()](https://developer.wordpress.org/reference/classes/wp_sitemaps/register_rewrites/)`wp-includes/sitemaps/class-wp-sitemaps.php` |

Registers sitemap rewrite tags and routing rules.

  | 
| [WP_Taxonomy::add_rewrite_rules()](https://developer.wordpress.org/reference/classes/wp_taxonomy/add_rewrite_rules/)`wp-includes/class-wp-taxonomy.php` |

Adds the necessary rewrite rules for the taxonomy.

  | 
| [WP_Post_Type::add_rewrite_rules()](https://developer.wordpress.org/reference/classes/wp_post_type/add_rewrite_rules/)`wp-includes/class-wp-post-type.php` |

Adds the necessary rewrite rules for the post type.

  |

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

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

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 3 content](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#comment-content-1829)
 2.    [bcworkz](https://profiles.wordpress.org/bcworkz/)  [  10 years ago  ](https://developer.wordpress.org/reference/functions/add_rewrite_tag/#comment-1829)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%23comment-1829)
     Vote results for this note: 10[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%23comment-1829)
 4.  In the following examples, imagine a site has a custom taxonomy ‘location’ and
     all posts are assigned a location term like “Paris” or “Madrid”. We add a rewrite
     tag “%location%” to establish the `location` query var. We also add a rewrite 
     rule so that an URL such as _example.com/goto/madrid/budget-lodging/_ is properly
     handled.
 5.      ```php
         add_action('init', 'add_my_rewrites');
         function add_my_rewrites() {
             add_rewrite_tag('%location%', '([^&]+)', 'location=');
             add_rewrite_rule('^goto/([^/]*)/([^/]*)/?','index.php?location=$matches[1]&name=$matches[2]','top');
         }
         ```
     
 6.  Even though rewrite tags look just like permalink structure tags, if you try to
     use your rewrite tag in a permalink structure, the URLs generated by WordPress
     will look something like _example.com/goto/%location%/budget-lodging/_. The proper
     term does not replace the rewrite tag as you might expect. To make your tag behave
     like a structure tag, use the “post_link” filter to replace the tag with the proper
     term.
 7.      ```php
         // Assign value to %location% rewrite tag
         add_filter('post_link', 'my_filter_post_link', 10, 2 );
         function my_filter_post_link( $permalink, $post ) {
     
             // bail if %location% tag is not present in the url:
             if ( false === strpos( $permalink, '%location%' ) ) {
                 return $permalink;
             }
             $terms = wp_get_post_terms( $post->ID, 'location' );
             // set location, if no location is found, provide a default value.
             if ( 0 < count( $terms ) ) {
                 $location = $terms[0]->slug;
             } else {
                 $location = 'timbuktu';
                 $location = urlencode( $location );
                 $permalink = str_replace('%location%', $location , $permalink );
             }
             return $permalink;
         }
         ```
     
 8.  Anytime you change something related to the Rewrite API, don’t forget to flush
     the rewrite rules! This can be done without code by going to Permalink Settings
     and clicking Save Changes. You don’t actually need to make any changes on the 
     settings screen.
 9.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%3Freplytocom%3D1829%23feedback-editor-1829)
 10.  [Skip to note 4 content](https://developer.wordpress.org/reference/functions/add_rewrite_tag/?output_format=md#comment-content-4549)
 11.   [Akira Tachibana](https://profiles.wordpress.org/atachibana/)  [  6 years ago  ](https://developer.wordpress.org/reference/functions/add_rewrite_tag/#comment-4549)
 12. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%23comment-4549)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%23comment-4549)
 13. (From Codex)
      **Example** The following will register a tag called ‘film_title’:
 14.     ```php
         <?php
             function custom_rewrite_tag() {
                 add_rewrite_tag('%film_title%', '([^&]+)');
             }
             add_action('init', 'custom_rewrite_tag', 10, 0);
         ?>
         ```
     
 15. This is particularly important when you are using rewrites with custom page templates.
 16. **Retrieving the Value of a Rewritten URL**
      With a rewrite tag defined, you can
     now retrieve the value of your rewritten querystring variables using WordPress’s
     $wp_query variable. To get the value of the above tag out of a rewrite, you could
     use the following in your page template:
 17.     ```php
         $wp_query->query_vars['film_title']
         ```
     
 18. Note that using $_GET on a rewritten URL will not work, even if the rewrite includes
     the querystring variables. You must use $wp_query.
 19.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fadd_rewrite_tag%2F%3Freplytocom%3D4549%23feedback-editor-4549)

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