Wrapper Field Type

The Wrapper field type allows you to visually group multiple fields together without nesting their values. Unlike the Group field type, which stores child values in a nested array, the Wrapper is a purely visual container — its children store their values flat at the parent level.

Field Type: `wrapper`

array(
	'type'  => 'wrapper',
	'items' => array(
		'name' => array(
			'type'  => 'text',
			'label' => 'Name',
		),
		'email' => array(
			'type'  => 'email',
			'label' => 'Email Address',
		),
		'phone' => array(
			'type'  => 'tel',
			'label' => 'Phone Number',
		),
	),
)

Properties

For Default Field Properties, see Field Types Definition.

Specific Properties

items (array) — An array of field definitions that make up the wrapper's content. Each item is a complete field definition with its own type, label, and other properties.
tag (string) — The HTML tag used for the wrapper container element. Defaults to div. You can use any valid HTML tag such as section, fieldset, aside, etc.
class_name (string) — A CSS class name added to the wrapper container element. This is applied alongside the default wpifycf-field-wrapper class.

Stored Value

This field does not store its own value. Children store their values flat at the parent level.

Comparison with Group

Given the same child fields, here is how values are stored:

Group stores nested values:

// group field with id 'contact_group'
array(
	'contact_group' => array(
		'name'  => 'John Doe',
		'email' => 'john@example.com',
		'phone' => '555-123-4567',
	),
)

Wrapper stores flat values:

// wrapper field with id 'contact_wrapper'
// Children are stored at the same level as the wrapper:
array(
	'name'  => 'John Doe',
	'email' => 'john@example.com',
	'phone' => '555-123-4567',
)

Example Usage

Basic Visual Grouping

Use a wrapper to visually separate a section of fields without affecting data structure:

'contact_section' => array(
	'type'  => 'wrapper',
	'items' => array(
		'first_name' => array(
			'type'     => 'text',
			'label'    => 'First Name',
			'required' => true,
		),
		'last_name' => array(
			'type'     => 'text',
			'label'    => 'Last Name',
			'required' => true,
		),
		'email' => array(
			'type'  => 'email',
			'label' => 'Email',
		),
	),
)

All three values (first_name, last_name, email) are stored flat at the root level.

Wrapper Inside a Group

When a wrapper is placed inside a group, its children's values stay flat within the group's namespace:

'profile' => array(
	'type'  => 'group',
	'label' => 'Profile',
	'items' => array(
		'avatar' => array(
			'type'  => 'attachment',
			'label' => 'Avatar',
		),
		'details_wrapper' => array(
			'type'  => 'wrapper',
			'items' => array(
				'bio' => array(
					'type'  => 'textarea',
					'label' => 'Bio',
				),
				'website' => array(
					'type'  => 'url',
					'label' => 'Website',
				),
			),
		),
	),
)

The stored value looks like this — bio and website sit alongside avatar inside the group:

array(
	'profile' => array(
		'avatar'  => 123,
		'bio'     => 'A short bio...',
		'website' => 'https://example.com',
	),
)

Custom HTML Tag

You can change the wrapper's HTML tag to add semantic meaning:

'settings_section' => array(
	'type'      => 'wrapper',
	'tag'       => 'section',
	'class_name' => 'my-settings-section',
	'items'     => array(
		'enable_feature' => array(
			'type'  => 'toggle',
			'label' => 'Enable Feature',
			'title' => 'Turn on the advanced feature',
		),
		'feature_mode' => array(
			'type'    => 'select',
			'label'   => 'Feature Mode',
			'options' => array(
				'basic'    => 'Basic',
				'advanced' => 'Advanced',
			),
		),
	),
)

With Conditions

Use a wrapper to show or hide a block of related fields together based on a condition:

'show_social' => array(
	'type'  => 'toggle',
	'label' => 'Show Social Links',
	'title' => 'Display social media links',
),
'social_wrapper' => array(
	'type'       => 'wrapper',
	'conditions' => array(
		array( 'field' => 'show_social', 'value' => true ),
	),
	'items'      => array(
		'twitter' => array(
			'type'  => 'url',
			'label' => 'Twitter URL',
		),
		'facebook' => array(
			'type'  => 'url',
			'label' => 'Facebook URL',
		),
		'linkedin' => array(
			'type'  => 'url',
			'label' => 'LinkedIn URL',
		),
	),
)

When the toggle is off, all three social link fields are hidden together.

Field Factory

$f = new \Wpify\CustomFields\FieldFactory();

$f->wrapper(
	items: array(
		$f->text( label: 'First Name' ),
		$f->text( label: 'Last Name' ),
	),
	tag: 'div',
	class_name: 'my-wrapper',
);

Notes

The key difference from the Group field type is that the wrapper does not nest values. Children store their values flat at the parent level.
By default, the wrapper sets renderOptions to noLabel: true, noFieldWrapper: true, and noControlWrapper: true, so it renders with no label or extra wrapping markup.
Wrapper children participate in validation at the parent level. The validation system flattens wrapper items using flattenWrapperItems() so each child is validated individually.
Wrappers can be nested inside other wrappers or inside groups.
In PHP, the flatten_items() method hoists wrapper children to the parent level for meta registration and sanitization. This ensures each child field is registered as its own meta key.
The wrapper is ideal for applying conditions to a block of fields, adding semantic HTML structure, or visually organizing fields without changing how data is stored.

FilesExpand file tree

wrapper.md

Latest commit

History