Documentation

• Getting Started with ACF
• Installation
• Creating a Field Group
• Field Settings
• Displaying values in your theme
• Code Examples

Updates

• How to activate
• How to update
• Known Issues
• Upgrade Guide – ACF PRO
• Upgrade Guide – Version 4
• Upgrade Guide – Version 5

Locations

• Adding fields to a taxonomy term
• Adding fields to Media Attachments
• Adding fields to Menu Items
• Adding fields to Menus
• Adding fields to Posts
• Get values from a user
• Get values from a widget
• Get values from an options page
• How to get values from a comment

Tutorials

• Adding custom javascript to fields
• Adding custom settings to fields
• Bidirectional Relationships
• Creating a new field type
• Creating a WP archive with custom field filter
• Custom location rules
• Customize the WYSIWYG toolbars
• Dynamically populate a select field’s choices
• Moving WP elements (such as the content editor) within ACF fields
• Multilingual Custom Fields
• Querying relationship fields
• Translating this plugin
• Using acf_form to create a new post
• Working with Nested Repeaters

How To

• Create a front end form
• Debug, diagnose and solve
• Distributing ACF in a plugin / theme
• Get values from another post
• Hide the ACF menu
• Hiding empty fields
• Order posts by custom fields
• Query posts by custom fields
• Register fields via PHP
• Register multiple options pages
• Sort a repeater field

Features

• Local JSON
• Options Page
• Synchronized JSON

• Can I include ACF PRO within my theme or plugin?

  Yes, If your theme or plugin is premium (is not free) then you are allowed to include the ACF PRO plugin within your theme or plugin.

  If your theme or plugin is free, you are restricted to including only the free version of ACF. You can learn more about including ACF here.

  Please note that the license key must never be distributed in any way within a theme or plugin. This also works to your advantage as it prevents the customer of your plugin or theme updating the ACF PRO plugin and causing potential code related issues.

• Can’t access account

  If you are having difficulties logging in to your ACF account, you may be experiencing one of the following common issues.

  Using the wrong account

  The ACF websites features 2 login areas; one for store purchases, and one for support. Both areas use separate accounts so please make sure you are logging into the correct area.

  To login to to your store account, please visit https://www.advancedcustomfields.com/store/account/ and provide the email address and password used when purchasing a premium ACF add-on. If you have forgotten your password, please use the Lost your password? link. Note: Store accounts are generated upon purchase.

  To login to your support account, please visit http://support.advancedcustomfields.com/ and use the login form in the top right of the screen. If you have forgotten your password, please use the Lost your password? link. Note: Support accounts are not connected to store accounts and you can signup for a support account bellow the login form.

  Password Reset not working

  If the password reset form shows an error such as “No account found for …”, then there may be an error with your account. Please contact [email protected] and provide the relevant information for us to fix your account.

• Could not connect to update server

  An error on the ‘Custom Fields -> Updates’ page will appear when it is not possible for your website to connect to the ACF server. If you see an error, you will not be able to activate your license or download updates until the issue is fixed.

  Please find some possible error messages below and be sure to contact our support team for any help.

  Error connecting to update server (cURL error 51: SSL *.sgvps.net)

  This problem is caused by a mixture of our ACF web host’s server setup (siteground) and your server’s SNI/TLS settings. The issue can be solved either of the following:

  1. Web host: If possible, ask your web host to update the cURL version to one which supports SNI.
  2. WP: Use the https_ssl_verify filter to avoid the SSL detection (code snippet below)

  functions.php

  add_filter( 'https_ssl_verify', '__return_false' );

  Error connecting to update server (meta 0;/.well-known/captcha/)

  Full error message

  <html><meta http-equiv="refresh" content="0;/.well-known/captcha/"></meta></head></html>

  This error suggests the HTTP connection was blocked. Please contact your web host to find your outgoing IP address (different from your normal IP address) and contact our support team with all available info.

  Error connecting to update server (<)

  This error message is a broken version of the above ‘.well-known/captcha’ issue. Please see instructions above.

  HTTP_BAD_REQUEST

  This issue suggests there is a firewall or other ‘block’ refusing the outgoing connection to our update server. Please contact your web host and notify them that your website is unable to connect to the ACF server preventing plugin updates. Ask them to test a connection to the following URL and review the response. This will show any problems with PHP settings or internal firewalls.

  https://connect.advancedcustomfields.com

• Do you offer refunds?

  This depends on the reason given. We strongly suggest you try the free plugin first and watch the feature videos on the ACF PRO page to understand how the PRO version will benefit your work!

• Field value won’t save

  When editing a term or options page, you may find that ACF is not able to save a field’s value. This problem is in most cases easy to diagnose and fix. Please review the following cases for more information.

  Field name length

  ACF uses the field’s name (see field settings) to save a value into the database. When saving sub fields, the ‘save name’ is generated by the ancestors names + the row index and can become quite long. It is possible that the length of this ‘save name’ can become too long for the wp_options table, and WP will not be able to save the value at all.

  Both taxonomy term and options page values are saved into the wp_options table which has a character limit on the options_name column of 64 characters.

  An example of a nested (x2) sub field could be: category_1_global_header_images_0_header_image_0_header_image_title which is 67 characters long, or perhaps more if the term ID / row indexes are 10 or higher.

  The solution is to either increase the options_name character length of the DB, or reduce the length of your field names.

• How do licenses work?

  ACF PRO introduces a standard licensing system which unlocks future updates. There are currently 2 different licenses available, these are personal and developer. The personal license will unlock plugin updates on 1 website, and the developer  license will unlock plugin updates on unlimited websites.

  After purchasing an ACF PRO license, you will have access to the plugin files via your online store account, and can then use the license key within the wp-admin section of your website to activate and unlock plugin updates for the website.

  Can I upgrade my license?

  You can upgrade your license at any time. Simple login to your store account and follow the prompts. Your license will be upgraded and you will be charged the difference in cost!

  Can I downgrade my license?

  Currently, this functionality does not exist, however it will be considered in the future.

• Is there a limit on number of fields?

  It is commonly misconceived that there is a limit on the number of fields you can add to a field group. ACF does not contain a limit, however, your server does contain a limit on how many variables can be used on each page.

  To reiterate, ACF is not limiting the number of fields you can save, instead, the server is simply terminating the save process before ACF can finish it’s job.

  The most common solution is to increase your max_vars setting. This is a PHP setting which determines how many variables can be used in one page load. By increasing this limit, you will allow ACF to complete it’s job.

  php.ini

  You can increase this setting by creating a php.ini file. This file may already exist on your server, but it is most likely you will need to create this yourself. Please note that your web host will be happy to help you create this file, so please contact them if you run into any difficulties.

  In the php.ini file, you can add this to bump up your limit to 3000

  max_input_vars = 3000
  suhosin.get.max_vars = 3000
  suhosin.post.max_vars = 3000
  suhosin.request.max_vars = 3000

  htaccess

  If you do not wish to create a php.ini file, it is also possible to update these settings via the .htaccess file in the root of your website folder. This method is easier, however it may not work on all servers. Please contact them if you run into any difficulties.

  php_value max_input_vars 3000
  php_value suhosin.get.max_vars 3000
  php_value suhosin.post.max_vars 3000
  php_value suhosin.request.max_vars 3000

• PayPal error during checkout

  If you encounter a PayPal error during checkout, please work through the following steps:

  1. Diagnose error

  If a PayPal error code is displayed, copy and paste the error code into Google to research the error description. If a solution is found, please follow the instructions and retry your purchase from ACF.

  2. Refresh cart

  If no solution can be found for the PayPal error, please open up a browser (firefox, safari or chrome) different to the one used for purchase, and attempt to purchase the premium add-on again from the ACF store. This ‘refresh’ will ensure no session or cache data is corrupt.

  3. Contact support

  If the above does not prove successfully, please email [email protected] with a detailed explanation of the issue and be sure to include any PayPal error codes.

• Value not loading on Posts page

  When viewing an archive page, you may find that ACF is unable to load data from the page as expected. This is because an archive page modifies the WP Query so that the global $post is not longer a “page”, but a selection of post objects. This change to the global $post is what prevents ACF from loading data from the correct location.

  This problem is most commonly experienced when changing the Reading Settings -> Front page displays setting to a static page, and then choosing a custom Posts page.

  The problem

  Here is some example code or a basic home.phptemplate file. This file is used to display the latest posts (Posts page setting). Please take note of the <h1> tag which should display a custom field on the page, however, this will always appear blank because (as described above) ACF does not know which page to load the data from.

  <?php get_header(); ?>
  
  	<h1><?php the_field('heading'); ?></h1>
  
  	<div id="primary" class="content-area">
  		<div id="content" class="site-content" role="main">
  		<?php if ( have_posts() ) : ?>
  
  			<?php /* The loop */ ?>
  			<?php while ( have_posts() ) : the_post(); ?>
  				<?php get_template_part( 'content', get_post_format() ); ?>
  			<?php endwhile; ?>
  
  			<?php twentythirteen_paging_nav(); ?>
  
  		<?php else : ?>
  			<?php get_template_part( 'content', 'none' ); ?>
  		<?php endif; ?>
  
  		</div><!-- #content -->
  	</div><!-- #primary -->
  
  <?php get_sidebar(); ?>
  <?php get_footer(); ?>

  The solution

  The simple solution is to tell ACF to load the data from the ‘Posts page’. You can do this by adding a second parameter to the get_field or the_field functions. This second parameter will contain the correct ID which can be found using  get_option('page_for_posts') like so:

  <?php get_header(); ?>
  
  	<h1><?php the_field('heading', get_option('page_for_posts')); ?></h1>
  
  	<div id="primary" class="content-area">
  		<div id="content" class="site-content" role="main">
  		<?php if ( have_posts() ) : ?>
  
  			<?php /* The loop */ ?>
  			<?php while ( have_posts() ) : the_post(); ?>
  				<?php get_template_part( 'content', get_post_format() ); ?>
  			<?php endwhile; ?>
  
  			<?php twentythirteen_paging_nav(); ?>
  
  		<?php else : ?>
  			<?php get_template_part( 'content', 'none' ); ?>
  		<?php endif; ?>
  
  		</div><!-- #content -->
  	</div><!-- #primary -->
  
  <?php get_sidebar(); ?>
  <?php get_footer(); ?>

• What data is recorded upon activation

  Each time an ACF PRO license key is activated, the following data is sent to the ACF website and saved to later validate activations and download updates:

  • ACF license key
  • ACF installed version
  • WP site name
  • WP site url
  • WP installed version
  • WP language
  • WP timezone

  No data such as usernames or emails are recorded, only geographic based data to see where ACF PRO is being used around the world.

• What is ACF PRO?

  ACF PRO is a new plugin which is being released alongside ACF version 5.

  ACF PRO is stand alone plugin which does not require the free version to be installed. ACF PRO is best though of as the free ACF plugin but with a whole lot of awesomeness on top! The awesomeness is made up of the 4 premium add-ons (repeater field, flexible content field, gallery field and options page).

• What kind of support do you provide?

  Help Desk

  Support is currently provided via our email help desk. Questions are generally answered within 24 hours, with the exception of weekends and Australian holidays. We answer questions related to ACF, it’s usage and provide minor customization guidance. We cannot guarantee support for questions which include custom theme code, or 3rd party plugin conflicts & compatibility.

  Community Forums

  Our Community Forums provide a great resource for searching and finding previously answered and asked support questions. You may create a new thread on these forums, however, it is not guaranteed that you will receive an answer from our support team. This is more of an area for developers to talk to one another, post ideas, plugins and provide basic help.

  In addition, please read our many documentation articles available on our site.

• Where do I enter my activation code?

  On purchase of an ACF PRO license or an ACF premium add-on, you will be given a download link and a license key. Depending on which version of ACF is installed, this license key has different uses:

  ACF PRO

  ACF PRO uses the license key to unlock updates. Updates will appear in the plugins admin page just like any other plugin.

  To activate your license key and unlock plugin updates, navigate to the ‘Custom Fields > Updates’ admin page and enter your license key.

  

  Add-ons (ACF v4)

  Your license key is not required to unlock plugin updates.

  Each Add-on will receive updates in the plugins admin page just like any other plugin.

  Add-ons (ACF v3)

  Your license key is required to unlock add-on functionality.

  To unlock your add-on functionality, navigate to the ‘Custom Fields > Settings’ admin page and enter your license key.

• Who can access support?

  Support is provided for free to everyone, without any bias to customers or beginners. Because this support service is provided for free, please take this into consideration when creating a ticker and waiting for a reply.

  Please research your issue and read the relevant documentation before asking a question. This will help free up our support team and allow for faster development on the plugin which we all love.

• WYSIWYG field is missing toolbar buttons

  If the WYSIWYG field is missing the toolbar buttons, it is most likely that you have a Javascript (JS) error on the page. Any JS error on the page will prevent ACF from creating the WYSIWYG tinyMCE editor. Bellow are some screenshots to demonstrate how the WYSIWYG field can appear.

  

  Broken (Js Error)

  

  Correct

  
  

  To solve the issue, please open up the inspector (in chrome / safari) or firebug (in firefox) and select the console tab. Refresh the page and take note of any red JS errors that appear.

  Most JS errors can be solved by editing the problematic script, however, some JS errors occur due to conflicts between plugins / themes. Please take note of the file that causes the error and contact the relevant developer.

Have a different question?

Submit a ticket to our friendly support team and let us help solve your issue.

Open a new support ticket