WordPress at Your Fingertips

register_taxonomy() WP 1.0

Creates or modifies a taxonomy object.

Note: Do not use before the init hook.

A simple function for creating or modifying a taxonomy object based on the parameters given. If modifying an existing taxonomy object, note that the $object_type value from the original registration will be overwritten.

Hooks from the function


WP_Taxonomy|WP_Error. The registered taxonomy object on success, WP_Error object on failure.


register_taxonomy( $taxonomy, $object_type, $args );
$taxonomy(string) (required)
Taxonomy key, must not exceed 32 characters.
$object_type(array|string) (required)
Object type or array of object types with which the taxonomy should be associated.

Array or query string of arguments for registering a taxonomy.

Default: array()

  • labels(string[])
    An array of labels for this taxonomy. By default, Tag labels are used for non-hierarchical taxonomies, and Category labels are used for hierarchical taxonomies. See accepted values in get_taxonomy_labels().
    Default: empty array

  • description(string)
    A short descriptive summary of what the taxonomy is for.
    Default: ''

  • public(true|false)
    Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users. The default settings of $publicly_queryable, $show_ui, and $show_in_nav_menus are inherited from $public.

  • publicly_queryable(true|false)
    Whether the taxonomy is publicly queryable. If not set, the default is inherited from $public

  • hierarchical(true|false)
    Whether the taxonomy is hierarchical.
    Default: false

  • show_ui(true|false)
    Whether to generate and allow a UI for managing terms in this taxonomy in the admin. If not set, the default is inherited from $public (default true).

  • show_in_menu(true|false)
    Whether to show the taxonomy in the admin menu. If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown. $show_ui must be true. If not set.
    Default: inherited from $show_ui (default true)

  • show_in_nav_menus(true|false)
    Makes this taxonomy available for selection in navigation menus. If not set, the default is inherited from $public (default true).

  • show_in_rest(true|false)
    Whether to include the taxonomy in the REST API. Set this to true for the taxonomy to be available in the block editor.

  • rest_base(string)
    To change the base url of REST API route.
    Default: $taxonomy

  • rest_controller_class(string)
    REST API Controller class name.
    Default: 'WP_REST_Terms_Controller'

  • show_tagcloud(true|false)
    Whether to list the taxonomy in the Tag Cloud Widget controls. If not set, the default is inherited from $show_ui (default true).

  • show_in_quick_edit(true|false)
    Whether to show the taxonomy in the quick/bulk edit panel. It not set, the default is inherited from $show_ui (default true).

  • show_admin_column(true|false)
    Whether to display a column for the taxonomy on its post type listing screens.
    Default: false

  • meta_box_cb(true|false|callable)
    Provide a callback function for the meta box display. If not set, post_categories_meta_box() is used for hierarchical taxonomies, and post_tags_meta_box() is used for non-hierarchical. If false, no meta box is shown.

  • meta_box_sanitize_cb(callable)
    Callback function for sanitizing taxonomy data saved from a meta box. If no callback is defined, an appropriate one is determined based on the value of $meta_box_cb.

  • capabilities(string[])
    Array of capabilities for this taxonomy.

    • manage_terms(string)
      Default 'manage_categories'.

    • edit_terms(string)
      Default 'manage_categories'.

    • delete_terms(string)
      Default 'manage_categories'.

    • assign_terms(string)
      Default 'edit_posts'.
  • rewrite(true|false|array)
    Triggers the handling of rewrites for this taxonomy. To prevent rewrite, set to false. To specify rewrite rules, an array can be passed with any of these keys:
    Default: true, using $taxonomy as slug

    • slug(string)
      Customize the permastruct slug.
      Default: $taxonomy key

    • with_front(true|false)
      Should the permastruct be prepended with WP_Rewrite::$front.
      Default: true

    • hierarchical(true|false)
      Either hierarchical rewrite tag or not.
      Default: false

    • ep_mask(int)
      Assign an endpoint mask.
      Default: EP_NONE
  • query_var(string|true|false)
    Sets the query var key for this taxonomy. If false, a taxonomy cannot be loaded at ?{query_var}={term_slug}. If a string, the query ?{query_var}={term_slug} will be valid.
    Default: $taxonomy key

  • update_count_callback(callable)
    Works much like a hook, in that it will be called when the count is updated. Default _update_generic_term_count() for taxonomies attached to other object types, such as users.
    Default: _update_post_term_count() for taxonomies attached to post types, which confirms that the objects are published before counting them

  • default_term(string|array)
    Default term to be used for the taxonomy.

    • name(string)
      Name of default term.

    • slug(string)
      Slug for default term.
      Default: ''

    • description(string)
      Description for default term.
      Default: ''
  • sort(true|false)
    Whether terms in this taxonomy should be sorted in the order they are provided to wp_set_object_terms().
    Default: null which equates to false

  • args(array)
    Array of arguments to automatically use inside wp_get_object_terms() for this taxonomy.

  • _builtin(true|false)
    This taxonomy is a "built-in" taxonomy. INTERNAL USE ONLY! Default false.


  • Global. Array. $wp_taxonomies Registered taxonomies.


Since 2.3.0 Introduced.
Since 4.2.0 Introduced show_in_quick_edit argument.
Since 4.4.0 The show_ui argument is now enforced on the term editing screen.
Since 4.4.0 The public argument now controls whether the taxonomy can be queried on the front end.
Since 4.5.0 Introduced publicly_queryable argument.
Since 4.7.0 Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the Taxonomy in REST API.
Since 5.1.0 Introduced meta_box_sanitize_cb argument.
Since 5.4.0 Added the registered taxonomy object as a return value.
Since 5.5.0 Introduced default_term argument.

Code of register_taxonomy() WP 5.8.1

function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
	global $wp_taxonomies;

	if ( ! is_array( $wp_taxonomies ) ) {
		$wp_taxonomies = array();

	$args = wp_parse_args( $args );

	if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) {
		_doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' );
		return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) );

	$taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args );

	$wp_taxonomies[ $taxonomy ] = $taxonomy_object;


	// Add default term.
	if ( ! empty( $taxonomy_object->default_term ) ) {
		$term = term_exists( $taxonomy_object->default_term['name'], $taxonomy );
		if ( $term ) {
			update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
		} else {
			$term = wp_insert_term(
					'slug'        => sanitize_title( $taxonomy_object->default_term['slug'] ),
					'description' => $taxonomy_object->default_term['description'],

			// Update `term_id` in options.
			if ( ! is_wp_error( $term ) ) {
				update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );

	 * Fires after a taxonomy is registered.
	 * @since 3.3.0
	 * @param string       $taxonomy    Taxonomy slug.
	 * @param array|string $object_type Object type or array of object types.
	 * @param array        $args        Array of taxonomy registration arguments.
	do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );

	return $taxonomy_object;

WP extension (enhancement)

Any taxonomy

No comments
    Log In