[ Close ] Introducing Carbon Fields Version 3 - now with Gutenberg Blocks Support


Documentation > Complex Field > Setup Methods

Setup Methods

You can use the following methods to setup and customize the complex field.


This method is identical to Container add_fields method, where $fields is an array of fields.


There are 3 layouts available for displaying a complex field:

  • grid (default) – lists the complex groups as a grid. Each field in the group is displayed in a new line with the label first and the form controls after it
  • tabbed-horizontal – groups are displayed as horizontal tabs
  • tabbed-vertical – groups are displayed as vertical tabs

For tabbed layouts the group label will be displayed in the tabs navigation.

Tabbed layouts are intended to clean up the user interface of field-heavy pages.


Minimum number of rows. Must be greater than 0. Defaults to -1 (no limit).


Maximum number of rows. Must be greater than 0. Defaults to -1 (no limit).


Allows client code to change labels for this complex field. The following items are accepted:

  • plural_name — the plural label. Default is “entries”
  • singular_name — the singular label. Default is “entry”

Example usage:

use Carbon_Fields\Field;
use Carbon_Fields\Field\Complex_Field;

$employees_labels = array(
    'plural_name' => 'Employees',
    'singular_name' => 'Employee',

Field::make('complex', 'crb_employee_data')
        Field::make('text', 'name')->help_text('Name of employee'),
        Field::make('text', 'position')->help_text('Position title'),
        Field::make('image', 'image'),
        Field::make('rich_text', 'description'),


Allows for an Underscore template to be used in the fields group header.

The passed $template can also be a callback.

Example usage:

->add_fields('passenger', array(
    Field::make('text', 'name'),
    Field::make('text', 'years'),
    <# if (name) { #>
        Passenger: {{ name }} {{ years ? "(" + years + ")" : "" }}
    <# } #>
->add_fields('driver', array(
    Field::make('text', 'name'),
    Field::make('text', 'drivers_license_id'),
    Field::make('image', 'picture'),
    <# if (name && drivers_license_id) { #>
        Driver: {{ name }}, {{ drivers_license_id }}
    <# } #>

Excited about Carbon Fields? Spread the word!