Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Display Advanced Custom Fields in WordPress (Step by Step)

How to Display Advanced Custom Fields in WordPress (Step by Step)

Short answer

ACF does not show fields on the front end by itself. Add get_field() or the_field() to a theme template inside the loop, escape the output, or use a page builder's dynamic tags or the ACF shortcode to place values without code.

Key takeaways

  • ACF stores data but does not display it automatically.
  • Use the Field Name, not the label, in code.
  • get_field() returns a value; the_field() prints it.
  • Escape output with esc_html(), esc_url() or wp_kses_post().
  • Use have_rows() and get_sub_field() for repeaters.
  • Elementor Pro dynamic tags and ACF blocks work without theme edits.

How do you display Advanced Custom Fields in WordPress?

Add the field's value to a theme template with get_field() or the_field(), or show it without code using a page builder's dynamic tags or the ACF shortcode.

Creating a field group only stores data. ACF does not print anything on the front end by itself, which is why many people add fields, fill them in, and then see nothing on the page.

To display a field, you have to tell your theme where to output it. There are four common ways, and the right one depends on your theme type and comfort with code.

This guide covers each method, with ready-to-use code for text, images, links and repeaters, plus tips on escaping output safely.

Which display method should you use?

Use PHP templates for full control in classic themes, a page builder's dynamic tags if you design with one, and the shortcode or ACF blocks for simple placements in block themes.

MethodNeeds codeWorks withBest for
PHP in theme templatesYesClassic and hybrid themesFull control over markup
Page builder dynamic tagsNoElementor Pro and similarDesigners using a builder
ACF shortcodeNoMost editorsOne-off values in content
ACF blocks or block bindingsSomeBlock themesSite Editor based sites

If you have not built your fields yet, start with our guide on using Advanced Custom Fields, then come back here.

Step 1: How do you find the field name?

Open Custom Fields > Field Groups, edit your group, and copy the Field Name shown under each field label.

ACF uses the Field Name, not the label, in code. A label like Event Date usually becomes a name like event_date.

Write the names down before you start. A typo in the field name is the most common reason a value does not appear.

Also note each field's Return Format setting, which appears on image, link, select, date and relationship fields. It controls what get_field() hands back, such as a URL, an ID or a full array, and it changes how your display code should look.

Step 2: How do you show a field in a theme template?

Open the matching template file in a child theme and call get_field() inside the loop, then echo the escaped value.

Edit a child theme so updates do not wipe your work. Our explainer on what a child theme is shows how to create one.

For a single post, the template is usually single.php or a more specific file such as single-event.php. Add your code inside the loop:

<?php
$event_date = get_field( 'event_date' );
if ( $event_date ) : ?>
    <p class="event-date"><?php echo esc_html( $event_date ); ?></p>
<?php endif; ?>

The get_field() documentation explains that it returns the value for the current post by default. It accepts a second argument for a different post ID.

The if check means nothing prints when the field is empty, so you do not get empty tags. PHP's if statement docs cover the syntax if you are new to it.

What is the difference between get_field() and the_field()?

get_field() returns the value so you can check and format it, while the_field() prints it straight away.

the_field() is a shortcut for echoing a value. It is fine for simple text, but get_field() is more flexible because you can test for empty values, change formats and escape the output exactly how you need.

Recent ACF versions escape HTML output from the_field() for security. If a field holds trusted HTML, such as a WYSIWYG field, use get_field() and the right WordPress escaping function. The escaping data handbook page lists them:

  • esc_html() for plain text.
  • esc_url() for links and image sources.
  • esc_attr() for HTML attributes.
  • wp_kses_post() for rich text that may contain safe HTML.

How do you display image fields?

Set the image field's return format to Image ID, then use wp_get_attachment_image() so WordPress outputs a responsive image with srcset and alt text.

<?php
$image_id = get_field( 'hero_image' );
if ( $image_id ) {
    echo wp_get_attachment_image( $image_id, 'large' );
}
?>

The wp_get_attachment_image() reference lists the size names and extra attributes you can pass.

If your field returns an array instead, use the url and alt keys from the array. Returning an ID is usually cleaner because WordPress handles sizes for you.

Each field type returns a different kind of value, so check its return format and output the parts you need.

Field typeTypical return valueHow to display
Text, number, emailA string or numberesc_html()
LinkArray with url, title, targetBuild an a tag with esc_url()
Select or radioValue, label or bothesc_html() the part you want
True / Falsetrue or falseUse in an if check
Date pickerFormatted stringSet return format in field settings
Post object or relationshipPost object or array of postsLoop and use get_the_title()

A link field example:

<?php
$link = get_field( 'cta_link' );
if ( $link ) : ?>
    <a href="<?php echo esc_url( $link['url'] ); ?>" target="<?php echo esc_attr( $link['target'] ?: '_self' ); ?>">
        <?php echo esc_html( $link['title'] ); ?>
    </a>
<?php endif; ?>

How do you display repeater fields?

Loop through rows with have_rows() and the_row(), then use get_sub_field() for each column inside the loop.

Repeaters are an ACF PRO feature. The have_rows() documentation shows the full pattern.

<?php if ( have_rows( 'team_members' ) ) : ?>
    <ul class="team">
    <?php while ( have_rows( 'team_members' ) ) : the_row(); ?>
        <li>
            <strong><?php echo esc_html( get_sub_field( 'name' ) ); ?></strong>
            <?php echo esc_html( get_sub_field( 'role' ) ); ?>
        </li>
    <?php endwhile; ?>
    </ul>
<?php endif; ?>

The same pattern works for flexible content, where you also check get_row_layout() to decide which markup to print.

How do you display fields from options, terms or users?

Pass a second argument to get_field() that tells ACF where the value lives, such as option, a term reference or a user reference.

  • Options page (PRO): get_field( 'footer_text', 'option' )
  • Category or term: get_field( 'banner', 'category_12' ) or pass the term object
  • User: get_field( 'job_title', 'user_5' )
  • Another post: get_field( 'price', 42 )

On a category archive, get_queried_object() returns the current term, which you can pass straight in.

Options pages are useful for site-wide content such as a phone number, a footer notice or social links. You set the value once and display it in the header, footer or any template without repeating it on every post.

How do you display fields without code?

Use Elementor Pro's dynamic tags, the ACF shortcode, or ACF blocks, depending on how you build pages.

In Elementor Pro, click the dynamic tags icon next to a widget field and choose an ACF tag, then pick your field. Our guide on using Elementor templates covers building a single post template where this works best.

ACF also offers a shortcode, such as [acf field=“event_date”]. Newer ACF versions turn the shortcode off by default for security, so check the ACF shortcode documentation for how to enable it before relying on it.

In block themes, there are no PHP templates to edit in the usual way. Options include ACF blocks, which you register with PHP and a block.json file, or newer block binding features. Our explainer on what a block theme is gives background.

Why is your ACF field not displaying?

Most blank fields come from a wrong field name, code placed outside the loop, an empty value, or a template file that is not actually loading.

Check these in order:

  • Confirm the Field Name matches your code exactly.
  • Make sure the post really has a value saved in that field.
  • Put the code inside the loop, or pass the post ID as the second argument.
  • Check the right template is loading. The template hierarchy shows which file WordPress picks, and Query Monitor tells you which one loaded.
  • Look for PHP errors with WP_DEBUG on a staging site.
  • Clear page and object caches after changes.

The free ACF plugin is in the WordPress plugin directory, and its support forum is a good place to ask if you are still stuck.

How do you keep ACF output clean and safe?

Always check for empty values, escape everything you print, and keep display logic in template parts so it is easy to reuse.

A few habits pay off:

  • Wrap each field in an if check so empty fields print nothing.
  • Escape every value with the right function for its context.
  • Move repeated markup into template parts and call get_template_part().
  • Name fields clearly and consistently across groups.

If you are building custom content types around your fields, our guide on creating a custom post type pairs well with this one.

Frequently asked questions

Why are my ACF fields not showing on the page?

ACF never prints fields automatically. You must add code to a template or use a dynamic tag, shortcode or block. If you already did, check the field name, confirm the post has a saved value, and make sure the code runs inside the loop.

Should I use get_field() or the_field()?

Use get_field() in most cases. It returns the value so you can check whether it is empty, format it and escape it properly. the_field() prints straight away, which is fine for simple text but gives you less control.

Can I display ACF fields without editing theme files?

Yes. Elementor Pro and other builders offer dynamic tags that pull ACF values into widgets. ACF also has a shortcode, although newer versions disable it by default, and ACF blocks let you display fields in the block editor.

How do I show an ACF field from another post?

Pass the post ID as the second argument to get_field(), for example get_field with the field name and 42. This works anywhere, including sidebars and footers, because it does not depend on the current post in the loop.

Do ACF fields work with block themes?

Yes, but block themes do not use PHP templates in the usual way. Display fields with ACF blocks, block bindings where supported, or a shortcode inside a block. Classic PHP template edits apply mainly to classic and hybrid themes.

Sources

  1. get_field() Advanced Custom Fields
  2. have_rows() Advanced Custom Fields
  3. ACF Shortcode Advanced Custom Fields
  4. Escaping Data WordPress Developer Resources
  5. wp_get_attachment_image() WordPress Developer Resources
  6. Advanced Custom Fields WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.