Description
The Relationship field provides a dual-column component to select one or more posts, pages or custom post type items, providing search, post type and taxonomy filtering controls to help find results.
Screenshots
Creating a Relationship field in an ACF field group.
The Relationship field UI as it might appear to content editors.
Settings
Filter by Post Type
Filters the selectable results by post type. When left empty, all post types are shown. Results are grouped by post type, so selected post types may be positioned in a specific order.Filter by Post Status
Filters the selectable results by status, i.e, Published, Draft, etc. Shows posts of every status if left empty.Filter by Taxonomy
Filters the selectable results via one or more taxonomy terms.Filters
Specifies which filters are displayed in the component. Select from “Search”, “Post Type”, and/or “Taxonomy”.Return Format Specifies the returned value format. Choose from Post Object (
WP_Post) or Post ID (integer).Required
Found on the Validation tab, this requires an input be entered, preventing the field from accepting empty values. Defaults to off.Minimum Posts
Sets a limit on how many posts are required.Maximum Posts
Sets a limit on how many posts are allowed.Instructions
Shows instructions when submitting data.Elements
Specifies which elements are displayed in each result. Select from “Featured Image”.Conditional Logic
Enabling this setting allows you to customize the logic which determines if the current field should be visible. Groups of conditional logic rules can be created to allow for multiple and/or statements.Bidirectional
Found on the Advanced tab, enabling this setting allows you to update a value in the target fields for each value selected for this field, adding or removing the Post ID, Taxonomy ID, or User ID of the item being updated. Please see Bidirectional Relationships for more information on using this setting to create bidirectional relationships directly in ACF’s UI.
Template usage
The Relationship field will return an array of items where each item is either a WP_Post object or an integer value depending on the Return Format set.
Display list of posts (with setup_postdata)
This example demonstrates how to loop over a Post Object value and display a list of clickable links. Here, we use a special function named setup_postdata() to enable the use of WordPress template functions. The field in this example uses Post Object as the Return Format, and is a multiple value.
<?php
$featured_posts = get_field('featured_posts');
if( $featured_posts ): ?>
<ul>
<?php foreach( $featured_posts as $post ):
// Setup this post for WP functions (variable must be named $post).
setup_postdata($post); ?>
<li>
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
<span>A custom field from this post: <?php the_field( 'field_name' ); ?></span>
</li>
<?php endforeach; ?>
</ul>
<?php
// Reset the global post object so that the rest of the page works correctly.
wp_reset_postdata(); ?>
<?php endif; ?>
Display list of posts (without setup_postdata)
This example demonstrates how to loop over a Post Object value and display a list of clickable links. Here, the global post variable is never changed, so all “post” related functions need a second parameter to specify which object. The field in this example uses Post Object as the Return Format, and is a multiple value.
<?php
$featured_posts = get_field('featured_posts');
if( $featured_posts ): ?>
<ul>
<?php foreach( $featured_posts as $featured_post ):
$permalink = get_permalink( $featured_post->ID );
$title = get_the_title( $featured_post->ID );
$custom_field = get_field( 'field_name', $featured_post->ID );
?>
<li>
<a href="<?php echo esc_url( $permalink ); ?>"><?php echo esc_html( $title ); ?></a>
<span>A custom field from this post: <?php echo esc_html( $custom_field ); ?></span>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
Notes
Customization
The Relationship field contains filters to customize the posts displayed, and the text displayed for each post.
Reverse query
It is possible to perform a reverse query on a post (post A) to find all the posts (post B, post C) which have selected it (post A). To learn more about a reverse query, please read this in-depth tutorial.
