Group

A Group holds several sub-fields that belong together (street, city and postal code of an address) and stores them as one JSON object in a single column.

Building a group

1. Add a field of type Group and give it a label and key.
2. Click + Add sub-field inside it and add fields. Each sub-field has its own type, settings, default, required and validation rules, exactly like a top-level field (see Settings every field has).
3. Save the field group.

Sub-field keys follow the same rules as field keys (lowercase letters, digits and underscores, no SQL words such as on, when or order) and must be unique inside the group.

What can go inside

Trying to save a disallowed type fails with a message such as "Repeater fields cannot be used inside another field." If you need a list inside a group, use a Repeater at the top level and put the group's fields next to it. Why Password is excluded: a group is saved as one block, and a password that was not retyped could not be kept.

Edit screen

The group appears as a framed card with its label (and the Group badge in the modern style). Sub-fields render inside it, in the same order and with the same width settings as normal fields. An empty definition shows "No sub-fields defined."

Required sub-fields are checked. If one is empty, the notice names it as Group label › Sub-field label (for example Address › Street). A required Group needs at least one filled sub-field.

Conditional logic inside a group compares sibling sub-fields only (see Settings every field has).

What is saved

Each sub-field value is cleaned by its own type, so a Number sub-field clamps, a Select sub-field refuses unknown values and a Text sub-field strips tags. Keys that are not sub-fields are dropped. A group with no values saves as empty.

Saving a group replaces its whole value. If you set only some sub-fields from code, the others are removed:

wpmcf_update_field( 'venue', 'address', [ 'street' => 'Main St', 'city' => 'Ankara' ], $post_id );
wpmcf_update_field( 'venue', 'address', [ 'street' => 'Other' ], $post_id );   // "city" is gone

Read, merge and write back when you need a partial update:

$address = (array) wpmcf_get_field( 'venue', 'address', $post_id );
$address['street'] = 'Other';
wpmcf_update_field( 'venue', 'address', $address, $post_id );

Template usage

$address = wpmcf_get_field( 'venue', 'address' );
// [
//   'street' => 'Main St',
//   'city'   => 'Ankara',
//   'zip'    => 6000,
//   'ok'     => 1,
//   'kind'   => 'h',
// ]

Things to know about the returned array:

• Keys are the sub-field keys, in no guaranteed order. MySQL may sort JSON keys. Never rely on position.
• Sub-values are the stored values. A True / false sub-field is 1 or 0 (not true / false), numbers are int or float, a Link is its own array, an Image is the attachment ID. A sub-field that was never filled may be missing, so use $address['city'] ?? ''.
• An unfilled Select can appear as null and a text sub-field as "".

Read one sub-field directly with path (or sub_key, which takes a single key):

$city = wpmcf_get_field( 'venue', 'address', null, [ 'path' => 'city' ] );        // "Ankara"
$zip  = wpmcf_get_field( 'venue', 'address', null, [ 'sub_key' => 'zip' ] );      // 6000

Printing

A Group itself prints nothing (wpmcf_the_field() and the shortcode return an empty string). Print a sub-field with path; it is formatted by the sub-field's own type, with the sub-field's own prefix and suffix:

wpmcf_the_field( 'venue', 'address', null, [ 'path' => 'kind' ] );   // Home   (a Select prints its label)
wpmcf_the_field( 'venue', 'address', null, [ 'path' => 'ok' ] );     // Yes

[wpmcf_field group="venue" field="address" path="city"]
[wpmcf_field group="venue" field="address" path="link" wrap="false"]
→ <a href="https://x.org">X</a>

The wrapper <span> and the prefix and suffix come from the sub-field's Display options, not the Group's. A sub-field with no value prints nothing.

Changing a group later

Renaming or changing the type of a sub-field remaps saved values in the background where it is safe; the builder explains what will happen before you confirm. See Field groups.

Limits

• Groups are stored as one value: you cannot add an index to a sub-field. You can still filter by one with a path such as group_key.field.sub_field in wpmcf_query (see Query posts by field value), but that condition cannot use an index.
• All sub-fields of the group are posted together. The server limit max_input_vars (often 1000) applies; very large groups and repeaters can exceed it. The edit screen blocks saving when the limit would be hit; see Repeater.
• A Group cannot be used as a Programmatic SEO data source column.

Troubleshooting

• "Group fields cannot be used inside another field." Containers cannot nest. Flatten the structure or use two top-level fields.
• My sub-field value is gone after a code update. Updating a group replaces the whole value; merge first.
• wpmcf_the_field() on my group prints nothing. Use path to print a sub-field.
• ok is 1, not true. Sub-values are the stored values; cast with (bool).