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

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


The $query parameter is optional. If it is omitted you must ensure that you call this on, or before, the ‘init’ hook. This is because $query defaults to "$tag=", and for this to work a new query var has to be added.



(string) (Required) Name of the new rewrite tag.


(string) (Required) Regular expression to substitute the tag for in rewrite rules.


(string) (Optional) String to append to the rewritten query. Must end in '='.

Default value: ''

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() 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 or earlier.

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() 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)


File: wp-includes/rewrite.php

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

	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 );


Version Description
2.1.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.