Ability: acf/create-field-group

Documentation Ability: acf/create-field-group

Last updated Mar 30, 2026

Overview

Creates a new ACF field group with fields and location rules.

Description

Creates a new field group in ACF with the specified title, fields, and location rules. The field group is automatically enabled for AI access.

Input

{
  "title": "Product Fields",
  "fields": [
    {
      "label": "Price",
      "name": "price",
      "type": "number"
    }
  ],
  "location": [
    [
      {
        "param": "post_type",
        "operator": "==",
        "value": "product"
      }
    ]
  ]
}

Required Properties

title (string) The title of the field group.

fields (array) Array of field configurations. See Field Schema below.

location (array) Location rules determining where the field group appears. See Location Schema below.

Optional Properties

description (string) A description for this field group.

position (string) Where to show the field group. Default: normal – normal: Below the content editor – side: In the sidebar – acf_after_title: After the post title

style (string) Field group style. Default: default – default: Standard metabox – seamless: No metabox styling

label_placement (string) Where to place field labels. Default: top – top: Above the field – left: Beside the field

instruction_placement (string) Where to show field instructions. Default: label – label: Below the label – field: Below the field

hide_on_screen (array) Items to hide from the edit screen. Options: permalink, the_content, excerpt, custom_fields, discussion, comments, revisions, slug, author, format, page_attributes, featured_image, categories, tags, send-trackbacks

active (boolean) Whether the field group is active. Default: true

show_in_rest (boolean) Whether to expose in REST API. Default: true

allow_ai_access (boolean) Whether to allow AI access. Default: true

ai_description (string) Description to help AI understand the purpose of this field group.

Field Schema

Each field in the fields array supports these properties:

Property	Type	Required	Description
label	string	Yes	Human-readable field label
name	string	Yes	Field name (used in code)
type	string	Yes	Field type (see below)
instructions	string	No	Help text for editors
required	boolean	No	Whether field is required
default_value	mixed	No	Default value
placeholder	string	No	Placeholder text
conditional_logic	array	No	Conditional display rules

Supported Field Types

Basic: text, textarea, number, range, email, url, password

Content: image, file, wysiwyg, oembed, gallery

Choice: select, checkbox, radio, button_group, true_false

Relational: link, post_object, page_link, relationship, taxonomy, user

Layout: group, repeater, flexible_content, clone

jQuery: google_map, date_picker, date_time_picker, time_picker, color_picker

Location Schema

Location rules are nested arrays representing AND/OR logic:

[
  [
    { "param": "post_type", "operator": "==", "value": "product" }
  ]
]

Outer array = OR groups, inner array = AND conditions within a group.

Location Parameters

Parameter	Description
post_type	Post type slug
post_template	Page template file
post_status	Post status
post_format	Post format
post_category	Category ID
post_taxonomy	Taxonomy term
page	Specific page ID
page_parent	Parent page ID
page_type	Page type (front, posts, top, parent, child)
user_form	User form (add, edit)
user_role	User role
taxonomy	Taxonomy screen
options_page	Options page slug

Operators

• ==: Is equal to
• !=: Is not equal to

Output

{
  "success": true,
  "field_group": {
    "ID": 123,
    "key": "group_abc123def456",
    "title": "Product Fields",
    "fields": [...],
    "location": [...],
    "active": true,
    "allow_ai_access": true
  },
  "field_group_id": 123,
  "message": "Field group 'Product Fields' created successfully."
}

Annotations

Annotation	Value
readonly	false
destructive	false
idempotent	false

Permissions

Requires the ACF capability (default: manage_options).

Example

Create a field group for an Event post type:

{
  "title": "Event Details",
  "fields": [
    {
      "label": "Event Date",
      "name": "event_date",
      "type": "date_picker",
      "required": true
    },
    {
      "label": "Event Time",
      "name": "event_time",
      "type": "time_picker"
    },
    {
      "label": "Location",
      "name": "location",
      "type": "text",
      "instructions": "Enter the venue name and address"
    },
    {
      "label": "Ticket Price",
      "name": "ticket_price",
      "type": "number",
      "default_value": 0
    }
  ],
  "location": [
    [
      {
        "param": "post_type",
        "operator": "==",
        "value": "event"
      }
    ]
  ],
  "ai_description": "Fields for event scheduling and ticketing information"
}

Notes

• Field keys are auto-generated if not provided
• The field group key is auto-generated based on a unique identifier
• Nested fields (repeater, group, flexible content) support the same field schema recursively
• Invalid field types or configurations return a WP_Error

Related

• Integrations: Ability: acf/field-groups
• Integrations: Ability: acf/create-custom-post-type
• Integrations: Ability: acf/custom-post-types
• Integrations: Ability: acf/create-custom-taxonomy
• Integrations: Ability: acf/custom-taxonomies