The Taxonomy field allows the selection of 1 or more taxonomy terms. Not only will this field save it’s selection as meta data, but you can also select an option to save the ‘post to term’ relationship data for WP_Query taxonomy queries.



  • Split setting ‘load_save_terms’ into ‘load_terms’ and ‘save_terms’ in version 5.2.7


Name Description
Taxonomy Select the taxonomy you wish to select term(s) from
Appearance Select the type of interface (checkbox, multi-select, radio buttons, select)
Allow Null Allow a ‘null’ value to be selected
Create Terms Allow new terms to be created whilst editing. Added in v5.2.3
Save Terms Connect selected terms to the post. Added in v5.2.7
Load Terms Load value from post’s terms. Added in v5.2.7
Return Value Select the value to be returned via the get_field function

Template usage

The taxonomy field will return 1 or more values (objects or IDs) depending on the field type setting. Below are some examples of how you can use this data.

Basic display (single value)

This example shows how to get and display a single term object. This would imply that your field type setting is radio button or select.


$term = get_field('taxonomy_field_name');

if( $term ): ?>

	<h2><?php echo $term->name; ?></h2>
	<p><?php echo $term->description; ?></p>

<?php endif; ?>


Basic display (multiple values)

This example shows how to get and loop over multiple selected term objects. This would imply that your field type setting is checkbox or multi-select.


$terms = get_field('taxonomy_field_name');

if( $terms ): ?>


	<?php foreach( $terms as $term ): ?>

		<h2><?php echo $term->name; ?></h2>
		<p><?php echo $term->description; ?></p>
		<a href="<?php echo get_term_link( $term ); ?>">View all '<?php echo $term->name; ?>' posts</a>

	<?php endforeach; ?>


<?php endif; ?>


Get field from selected term

This example shows how you can load a custom field value from the $term object. Passing the $term object as the $post_id parameter was introduced in version 4.3.3. Prior to this, you must construct a post_id value as described in this tutorial.


$term = get_field('taxonomy_field_name');

if( $term ): ?>

	<h2><?php echo $term->name; ?></h2>
	<p><?php echo $term->description; ?></p>
	<p>Color: <?php the_field('color', $term); ?></p>

<?php endif; ?>




It is possible to customise the taxonomy terms displayed by modifying the $args variable used to query the database.

There are 2 filters available to modify the query arguments. Only one filter is needed, however, the filter will change depending on the Appearance setting of your taxonomy field.

For the appearance settings ‘Select’ and ‘Multi Select’, please use the acf/fields/taxonomy/query filter.

For the appearance settings ‘Checkbox’ and ‘Radio’, please use the acf/fields/taxonomy/wp_list_categories filter.


It is possible to customise the text displayed for each taxonomy term item. To do this, please use the filter acf/fields/taxonomy/result


We use cookies to offer you a better browsing experience, analyze site traffic and personalize content. Read about how we use cookies and how you can control them in our Cookie Policy. If you continue to use this site, you consent to our use of cookies.