How to use and display the ACF File field

About the File field

The File field is one of many ACF field types, it allows you to "add" attachments from the Media Library to any page.

Unlike the Image field, that only allows images to be selected (.png, .jpg, .gif and such) the File field allows you to choose a file with any extension from your Media Library, including various file types, like .pdf and .doc

Also, unlike the Image field it doesn't provide a preview of the selected file, so you can only see the File Name and the File Size. Usually, developers use this field type to create a download or "open" file link.

The field supports many different file extensions. You can find the list of allowed extensions for all file types on the related wordpress.org page.

Return formats

ACF File field has 3 options in the Return Type setting: File Array, File URL, and File ID. This setting doesn't affect the field's look for admin editors. But controls the format of the value which you get back in code when you request the field value from the Database.

Therefore I would suggest that you use the 'File ID' option. It's the best choice for performance and allows you to get any extra data about the selected attachment, like File name or Upload Date. Steer clear of the 'File URL' option, unless you need this option for some specific goal. As it doesn't allow you to get any extra data about the attachment.

Behind the ACF scenes

As we mentioned the File field works with the Media Library and allows you to add all sorts of attachments to pages. But you need to know that when you "add" a file it actually means "attach", not copy. The field is just the middleman between a page and the Media Library and associates the ID from the file you've chosen to Post Meta of the current page. It means without creating duplicates or physical copies of the file.

Even in the case, when you are uploading a new attachment through the field upload dialogue box, the file will be uploaded to the Media Library like an ordinary attachment with the file field only storing the Attachment ID. In this way, you can "attach" one file to many pages and it won't create copies.

You would still need to give clear names for your attachments and you should really try and avoid uploading the same file multiple times. Because the Media Library doesn't know if the attachment being uploaded is a completely new one or if it already exists. So if you're unsure then do a quick search in the Media Library before uploading. Otherwise, you'll have a lot of headaches over time with multiple copies of the same thing.

Furthermore, the Return Format setting also doesn't affect the stored value. It's always an Attachment ID. In case you've not selected the 'File ID' Return Format, then every time you request the field the ACF plugin will do extra work to convert the saved Attachment ID to another format, that's why it's better for performance to use the native "File ID" option.

Display File field with PHP code

In most cases, we would need to turn the File field into a link to show to users. So when they try and download the attachment or open it in a new browser tab it's easy for them. To do this you would need to get the file URL (and probably the name too) and then create the HTML for the link.

The code will be different depending on the selected Return Type. Below we provided examples.

1. PHP code to display the File field with the "ID" Return Format:

<?php

// don't forget to replace 'file' with your field name
$fileID = get_field('file');
if ($fileID) {
   // $fileID is an ID (integer) of a Post with the Attachment type. 
   // we need to use the built-in WP functions to get necessary data
    $url = wp_get_attachment_url($fileID);
    $name = get_post($fileID)->post_title ?? '';
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='%s'>%s</a>", esc_attr($url), esc_attr($name), esc_html($name));
}

2. PHP code to display the File field with the "Array" Return Format:

<?php

// don't forget to replace 'file' with your field name
$fileData = get_field('file');
if ($fileData) {
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='%s'>%s</a>", 
     esc_attr($fileData['url']), esc_attr($fileData['filename']), esc_html($fileData['filename']));
}

3. PHP code to display the File field with the "URL" Return Format:

<?php

// don't forget to replace 'file' with your field name
$fileUrl = get_field('file');
if ($fileUrl) {
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='prices.pdf'>Prices.pdf</a>", esc_attr($fileUrl));
}

We've used the download attribute (read more) to let a client's browser know, that instead of opening this file must be downloaded. The value of the attribute will be used as the name of the downloading file. Remove the attribute if you want this file to be opened instead of downloaded.

With the "URL" Return Format we've to hardcode the file name. There is no way to use this code for different files or amend it without code editing. That's why it's better always to choose the "ID" Return Format.

You can find more information in the official ACF article.

Display File field with shortcodes

Shortcodes are one of the most powerful and easy to use WordPress features out there. Shortcodes allow you to "call" PHP functions directly in your editor, like Gutenberg. This allows you to display dynamic content pieces.

To create a shortcode you'd need to write PHP code. But we're not going to do that today, we're going to use a free plugin called ACF Views. That'll do all the work for us, and will allow you to display any ACF field, using automatically generated shortcodes. Read how to display ACF fields without coding to know all benefits of the shortcode approach.

Below we attached a video tutorial that shows how to display ACF fields on a single page using the shortcode way. The video is common for all the ACF field types. More video tutorials on the official YouTube channel.

But feel free to skip the video as below we provide a full step-by-step guide exactly for the ACF File field.

If you want to follow along you need to:

1. install the ACF Views plugin on your WordPress site. And don't forget to activate it. It's an add-on to ACF, so you'll also need to
2. Install the free Advanced Custom Fields (ACF) plugin and activate it.

Step 1. Creating a View

After you've activated the ACF Views plugin you'll see a new item in your admin menu, called "ACF Views".

That item has a sub-menu, with several items, but we'll only need to use the one called 'ACF Views'.

Click on the "Add New" button to create a View.

Note: The term "View" is the name given for the special Post Type the plugin provides. Every View is a list of ACF fields to display, so you may have many different Views to display different fields (or sets of fields) for different posts/pages.

Then give your View a name, you can use anything that describes the View. This name will only be displayed in the list of Views, making it easier to find. I've called my View "Page catalog".

Assigning fields

Now you'll need to assign a new field to your View. Click the 'Add Field' button and select your 'Group' from the dropdown. In my case, the group has the "Page fields" name. Then continue to select the target field from the list, I've selected "Catalog (file)".

Note: the field type is shown in the brackets after the file name. So you can easily identify the type of any field in the dropdown.

You should also see the type as "file". Define a "Link Label" for our future link. Or leave it empty, if you want the plugin to pick it up from the selected attachment.

Overall every View can have an unlimited amount of ACF fields, for our case, we'll use only one.

Click on the 'Publish' button to save and publish your View. As soon it's published you'll notice that Shortcodes were generated in a block on the right side of your View edit screen. Every View has its own shortcode with a unique ID (the shortcode structure is the same for all Views, but arguments are unique).

[acf_views view-id="xxxx" name="x"]

Now we need to copy the shortcode. For this goal click on the 'Copy to clipboard' button on the first shortcode.

Step 2. Paste the shortcode in place

Now that we've prepared everything we are ready to display the File field.

Visit your target page, this will be where you have the file field. Remember to check that there is an attachment in your File field, and paste the shortcode anywhere you'd like in the page content.

To paste the shortcode with the Gutenberg editor, just click on the plus button in the top bar and choose the "Shortcode" block from the list. Then paste your shortcode in the block and click the 'Update' button to save your post/page.

Visit the page to see the result. And if you've done everything correctly then you should see your selected file displayed in the content as a link, with your defined label. Or with the File Name of the attached File in case you've left it empty.

If you can't see your link, then go back and edit the page. Make sure you've attached a File to the ACF file field because if the field is empty it'll have nothing to display.

Final thoughts

You've taken a closer look at the ACF File field, and how to use and display it. We've shown the important aspects that you need to remember when using this field type.

It's useful to know that you can have multiple fields (even from different groups) in a single View, and you can style the fields output using the CSS code field (see the View's Advanced Tab). The plugin will add that CSS only on pages where you're using the shortcode. So you don't need to search for a place to put it.

Visit the ACF Views official website to get more information about the plugin, you can also find links to the plugin's YouTube channel that has video tutorials and the plugin Documentation. Those resources will help you get familiar with the plugin faster.