acf_form() │ ACF 1.0

Displays a form for adding or editing posts.

No Hooks.

Returns

null. Nothing.

Usage

<?php acf_form( $settings ); ?>

$settings(int/array)

An array of settings or the ID of a registered form. The array can contain the following keys:

$settings = [
	'id'                    => 'acf-form',
	'post_id'               => false,
	'new_post'              => false,
	'field_groups'          => false,
	'fields'                => false,
	'post_title'            => false,
	'post_content'          => false,
	'form'                  => true,
	'form_attributes'       => [],
	'return'                => '',
	'html_before_fields'    => '',
	'html_after_fields'     => '',
	'submit_value'          => __("Update", 'acf'),
	'updated_message'       => __("Post updated", 'acf'),
	'label_placement'       => 'top',
	'instruction_placement' => 'label',
	'field_el'              => 'div',
	'uploader'              => 'wp',
	'honeypot'              => true,
	'html_updated_message'  => '<div id="message" class="updated"><p>%s</p></div>',
	'html_submit_button'    => '<input type="submit" class="acf-button button button-primary button-large" value="%s" />',
	'html_submit_spinner'   => '<span class="acf-spinner"></span>',
	'kses'                  => true
]

• id(string) — unique form identifier. Default: acf-form
• post_id(Integer|String) — determines displayed and updated fields. Defaults to the current post ID; new_post creates a new post on saving. Default: false
• new_post(array) — settings for a new post when post_id is new_post; see wp_insert_post(). Default: false
• field_groups(array) — IDs/keys of field groups to override the displayed fields. Default: false
• fields(array) — field IDs/keys to override the displayed fields. Default: false
• post_title(Boolean) — whether to display a post-title field. Default: false
• post_content(Boolean) — whether to display the post-content field in the built-in WordPress editor. Default: false
• form(Boolean) — whether to create form elements; use when adding to an existing form. Default: true
• form_attributes(array) — an array of HTML attributes for the form element. Default: []
• return(string) — redirect URL after submission. %post_url% becomes the post URL and %post_id% becomes the post ID. Default: ''
• html_before_fields, html_after_fields(string) — additional HTML before or after fields. Default: ''
• submit_value(string) — submit-button label. Default: __("Update", 'acf')
• updated_message(string) — message displayed above the form after submission; false disables it. Default: __("Post updated", 'acf')
• label_placement(string) — label position: top or left. Default: 'top'
• instruction_placement(string) — instruction position: label or field. Default: 'label'
• field_el(string) — field wrapper element: div, tr, td, ul, ol, or dl. Default: 'div'
• uploader(string) — wp uploader or basic input for image and file fields. Default: 'wp'
• honeypot(Boolean) — whether to add hidden fields that prevent bot form submissions. Default: true
• html_updated_message, html_submit_button, html_submit_spinner(string) — HTML used for the update message, submit button, and spinner.
• kses(Boolean) — whether to sanitize all $_POST data with wp_kses_post(). Default: true

Examples

#1 Editing a simple post

This example demonstrates how to display a basic form for editing a simple post.

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

<div id="primary" class="content-area">
	<div id="content" class="site-content" role="main">
		<?php while ( have_posts() ) : the_post(); ?>
			<?php acf_form(); ?>
		<?php endwhile; ?>
	</div><!-- #content -->
</div><!-- #primary -->

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

#2 Edit title labels when enabled

If the form has 'post_title' => true, use acf/load_field/name=_post_title to change the title field’s label, placeholder, and instructions.

add_filter( 'acf/load_field/name=_post_title', 'air_post_title_acf_name' );

/**
 * Changes the label, placeholder, and instructions for the title field in an ACF form.
 *
 * @param array $field ACF field data array.
 * @return array The changed ACF field data array.
 */
function air_post_title_acf_name( $field ) {
	$field['label']        = 'Enter the post title';
	$field['placeholder']  = 'A post title is like air — you cannot do without it!';
	$field['instructions'] = 'Be sure to provide a title for your post, otherwise it will remain nameless like a ghost.';

	return $field;
}

#3 Editing specific post fields

This example demonstrates how to display a form that edits post meta-fields.

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

<?php acf_form([
	'post_id'       => 123,
	'post_title'    => false,
	'post_content'  => false,
	'submit_value'  => __('Update meta')
]); ?>

<?php get_footer(); ?>

#4 Creating a custom post

This example shows how to create a new custom post using a form submission.

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

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

<?php get_footer(); ?>