acf_add_local_field_group() │ ACF 5.7.10

Registers an ACF field group and adds its fields to local storage.

The group exists only while PHP runs. It is not saved in the database and is not displayed for editing on the ACF Field Groups page.

Registering through PHP makes it easier to move settings between environments and reduces database queries. If only group synchronization is needed, use Local JSON.

It is recommended to call the function inside the acf/include_fields action. At that point ACF has loaded and the function is guaranteed to be available.

Every group and field must have a unique key. If a group with that key is already registered, the function does not replace it and returns false.

If key is not specified, ACF creates it from title with the group_ prefix.

No Hooks.

Returns

boolean.

• true - the group and its fields are registered.
• false - a group with that key already exists.

Usage

acf_add_local_field_group( $field_group );

$field_group(array) (required)

Field-group settings.

• key(string)
  The unique group key. It usually starts with group_.

  If omitted, ACF creates the key from title.

• title(string)
  The group name. Displayed as the meta box title.
  Default: ''

• fields(array)
  An array of group fields. The settings for each field depend on its type.

  Each field key must be unique and usually starts with field_.
  Default: []

• location(array)
  Rules that determine the screens where the group is displayed.

  Outer rule groups are joined by “OR”. Rules within one group are joined by “AND”.

  Each rule contains:

  • param(string) (required)
    The condition type to check. For example, post_type, page_template, taxonomy, or block.

  • operator(string) (required)
    The comparison operator, usually == or !=.

  • value(string) (required)
    The value to compare.

• menu_order(int)
  The group order relative to other groups. Lower values appear first.
  Default: 0

• position(string)
  The group position on the edit screen.

  Possible values: acf_after_title, normal, side.
  Default: normal

• style(string)
  The meta-box style.

  Possible values: default, seamless.
  Default: default

• label_placement(string)
  The position of labels relative to fields.

  Possible values: top, left.
  Default: top

• instruction_placement(string)
  The position of field instructions.

  label displays an instruction below the label. field displays it below the field element.
  Default: label

• hide_on_screen(array|string)
  Standard edit-screen elements to hide.

  For example: the_content, excerpt, custom_fields, discussion, comments, slug, author, format, page_attributes, featured_image, revisions, categories, tags, send-trackbacks.

• active(bool)
  Enables or disables the group.
  Default: true

• description(string)
  The group description.
  Default: ''

• show_in_rest(bool|int)
  Allows use of the group fields through the REST API.
  Default: 0

• local(string)
  The local group source. The function sets it to php automatically.
  Default: php

Examples

#1 Register a field group for posts

Add a “Subtitle” text field to regular posts.

add_action( 'acf/include_fields', 'wpkama_register_post_fields' );

function wpkama_register_post_fields() {
	if ( ! function_exists( 'acf_add_local_field_group' ) ) {
		return;
	}

	acf_add_local_field_group(
		[
			'key'    => 'group_post_details',
			'title'  => 'Post details',
			'fields' => [
				[
					'key'   => 'field_post_subtitle',
					'label' => 'Subtitle',
					'name'  => 'post_subtitle',
					'type'  => 'text',
				],
			],
			'location' => [
				[
					[
						'param'    => 'post_type',
						'operator' => '==',
						'value'    => 'post',
					],
				],
			],
		]
	);
}

#2 Multiple display conditions

The group appears only on pages with the templates/landing.php template.

add_action( 'acf/include_fields', 'wpkama_register_landing_fields' );

function wpkama_register_landing_fields() {
	if ( ! function_exists( 'acf_add_local_field_group' ) ) {
		return;
	}

	acf_add_local_field_group(
		[
			'key'    => 'group_landing',
			'title'  => 'Landing settings',
			'fields' => [
				[
					'key'   => 'field_landing_heading',
					'label' => 'Heading',
					'name'  => 'landing_heading',
					'type'  => 'text',
				],
			],
			'location' => [
				[
					[
						'param'    => 'post_type',
						'operator' => '==',
						'value'    => 'page',
					],
					[
						'param'    => 'page_template',
						'operator' => '==',
						'value'    => 'templates/landing.php',
					],
				],
			],
		]
	);
}