acf_form()

Overview

This function creates a <form> to add or edit a post. There are many settings available to customize the form and these are set by adding to the $options array as explained below. You may also register a form using the acf_register_form() function.

Parameters

<?php acf_form( $options ); ?>
  • $options (string|array) either an array or settings or the ‘id’ of a registered form.

$settings array

$settings = array(

	/* (string) Unique identifier for the form. Defaults to 'acf-form' */
	'id' => 'acf-form',
	
	/* (int|string) The post ID to load data from and save data to. Defaults to the current post ID. 
	Can also be set to 'new_post' to create a new post on submit */
	'post_id' => false,
	
	/* (array) An array of post data used to create a post. See wp_insert_post for available parameters.
	The above 'post_id' setting must contain a value of 'new_post' */
	'new_post' => false,
	
	/* (array) An array of field group IDs/keys to override the fields displayed in this form */
	'field_groups' => false,
	
	/* (array) An array of field IDs/keys to override the fields displayed in this form */
	'fields' => false,
	
	/* (boolean) Whether or not to show the post title text field. Defaults to false */
	'post_title' => false,
	
	/* (boolean) Whether or not to show the post content editor field. Defaults to false */
	'post_content' => false,
	
	/* (boolean) Whether or not to create a form element. Useful when a adding to an existing form. Defaults to true */
	'form' => true,
	
	/* (array) An array or HTML attributes for the form element */
	'form_attributes' => array(),
	
	/* (string) The URL to be redirected to after the form is submit. Defaults to the current URL with a GET parameter '?updated=true'.
	A special placeholder '%post_url%' will be converted to post's permalink (handy if creating a new post)
	A special placeholder '%post_id%' will be converted to post's ID (handy if creating a new post) */
	'return' => '',
	
	/* (string) Extra HTML to add before the fields */
	'html_before_fields' => '',
	
	/* (string) Extra HTML to add after the fields */
	'html_after_fields' => '',
	
	/* (string) The text displayed on the submit button */
	'submit_value' => __("Update", 'acf'),
	
	/* (string) A message displayed above the form after being redirected. Can also be set to false for no message */
	'updated_message' => __("Post updated", 'acf'),
	
	/* (string) Determines where field labels are places in relation to fields. Defaults to 'top'. 
	Choices of 'top' (Above fields) or 'left' (Beside fields) */
	'label_placement' => 'top',
	
	/* (string) Determines where field instructions are places in relation to fields. Defaults to 'label'. 
	Choices of 'label' (Below labels) or 'field' (Below fields) */
	'instruction_placement' => 'label',
	
	/* (string) Determines element used to wrap a field. Defaults to 'div' 
	Choices of 'div', 'tr', 'td', 'ul', 'ol', 'dl' */
	'field_el' => 'div',
	
	/* (string) Whether to use the WP uploader or a basic input for image and file fields. Defaults to 'wp' 
	Choices of 'wp' or 'basic'. Added in v5.2.4 */
	'uploader' => 'wp',
	
	/* (boolean) Whether to include a hidden input field to capture non human form submission. Defaults to true. Added in v5.3.4 */
	'honeypot' => true,
	
	/* (string) HTML used to render the updated message. Added in v5.5.10 */
	'html_updated_message'	=> '<div id="message" class="updated"><p>%s</p></div>',
	
	/* (string) HTML used to render the submit button. Added in v5.5.10 */
	'html_submit_button'	=> '<input type="submit" class="acf-button button button-primary button-large" value="%s" />',
	
	/* (string) HTML used to render the submit button loading spinner. Added in v5.5.10 */
	'html_submit_spinner'	=> '<span class="acf-spinner"></span>',
	
	/* (boolean) Whether or not to sanitize all $_POST data with the wp_kses_post() function. Defaults to true. Added in v5.6.5 */
	'kses'	=> true
			
);

Notes

acf_form_head()

It is important to note that whilst the acf_form() function will create a form allowing you to input data, it will not perform the logic needed to save the data. This logic is handled by another function called acf_form_head(). To allow the form to save data, you will need to place the acf_form_head() function at the top of your page template before any HTML is rendered.

<tr>

If using the ‘field_el’ setting to render fields as a <tr> (table row) element, please be aware that the acf_form() function will not create the wrapping <table> or <tbody> elements. You may add these elements outside of the acf_form() function or use the ‘html_before_fields’ and ‘html_after_fields’ settings.

Examples

Basic

This example shows a basic acf_form to edit the current post.

<?php acf_form_head(); ?>
<?php get_header(); ?>

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Editing a specific post

This example shows how to target a specific post, customize the button label and hide the post title input.

<?php acf_form_head(); ?>
<?php get_header(); ?>

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(array(
					'post_id'	=> 123,
					'post_title'	=> false,
					'submit_value'	=> 'Update the post!'
				)); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Create a new post

This example shows how you can create a new post when submitting the form.

<?php acf_form_head(); ?>
<?php get_header(); ?>

	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">

			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>

				<?php acf_form(array(
					'post_id'		=> 'new_post',
					'new_post'		=> array(
						'post_type'		=> 'event',
						'post_status'		=> 'publish'
					),
					'submit_value'		=> 'Create a new event'
				)); ?>

			<?php endwhile; ?>

		</div><!-- #content -->
	</div><!-- #primary -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

AJAX

When using AJAX to display the acf_form HTML, please note that some extra PHP/JS must also be run to let ACF know there are new fields on the page which may require some JS initializing.

PHP

Please add the following code to the page within the <body> tags and before the wp_footer action. This will create a hidden WYSIWYG field and enqueue the required JS templates for the WP media popups.

PHP

acf_enqueue_uploader();

Javascript

Either place the following inline JS in the appended HTML, or run the JS on complete of your AJAX append. This will allow ACF to initialize the fields within the newly added HTML.

Javascript

<script type="text/javascript">
(function($) {
	
	// setup fields
	acf.do_action('append', $('#popup-id'));
	
})(jQuery);	
</script>

Security

Since version 5.6.5, ACF uses the wp_kses_post() function to sanitize content and strip out evil scripts. This sanitization can be disabled if needed by changing the form’s ‘kses’ setting to false.

If you are using an older version of ACF, we advise that you add the following filter to your functions.php file.

functions.php

function my_kses_post( $value ) {
	
	// is array
	if( is_array($value) ) {
	
		return array_map('my_kses_post', $value);
	
	}
	
	
	// return
	return wp_kses_post( $value );

}

add_filter('acf/update_value', 'my_kses_post', 10, 1);

Related