Awesome
ACF Builder Cheatsheet
This cheatsheet consists of ACF Field Type arguments for use with ACF Builder as well as the known (most of which are not documented) configuration methods to assist in building fields. While the below field types reveal all of the possible configuration passable in the field type config array, most have available chainable methods to assist in building out cleaner, more readable code.
If you are new to ACF Builder and would like to learn more, you can read my guide here.
Table of Contents
Field Types
You can find a full reference of available settings on the official ACF documentation.
Basic
Text
$builder
->addText('text_field', [
'label' => 'Text Field',
'instructions' => '',
'required' => 0,
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
'maxlength' => '',
]);
Textarea
$builder
->addTextarea('textarea_field', [
'label' => 'Textarea Field',
'instructions' => '',
'required' => 0,
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
'maxlength' => '',
'rows' => '',
'new_lines' => '', // Possible values are 'wpautop', 'br', or ''.
]);
Number
$builder
->addNumber('number_Field', [
'label' => 'Number Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
'min' => '',
'max' => '',
'step' => '',
]);
Range
$builder
->addRange('range_field', [
'label' => 'Range Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'min' => '',
'max' => '',
'step' => '',
'prepend' => '',
'append' => '',
]);
$builder
->addEmail('email_field', [
'label' => 'Email Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
]);
URL
$builder
->addUrl('url_field', [
'label' => 'URL Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
]);
Password
$builder
->addPassword('password_field', [
'label' => 'Password Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'placeholder' => '',
'prepend' => '',
'append' => '',
]);
Content
Wysiwyg
$builder
->addWysiwyg('wysiwyg_field', [
'label' => 'WYSIWYG Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'tabs' => 'all',
'toolbar' => 'full',
'media_upload' => 1,
'delay' => 0,
]);
Oembed
$builder
->addOembed('oembed_field', [
'label' => 'Oembed Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'width' => '',
'height' => '',
]);
Image
$builder
->addImage('image_field', [
'label' => 'Image Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'return_format' => 'array',
'preview_size' => 'thumbnail',
'library' => 'all',
'min_width' => '',
'min_height' => '',
'min_size' => '',
'max_width' => '',
'max_height' => '',
'max_size' => '',
'mime_types' => '',
]);
File
$builder
->addFile('file_Field', [
'label' => 'File Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'return_format' => 'array',
'library' => 'all',
'min_size' => '',
'max_size' => '',
'mime_types' => '',
]);
Gallery
$builder
->addGallery('gallery_field', [
'label' => 'Gallery Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'return_format' => 'array',
'min' => '',
'max' => '',
'insert' => 'append',
'library' => 'all',
'min_width' => '',
'min_height' => '',
'min_size' => '',
'max_width' => '',
'max_height' => '',
'max_size' => '',
'mime_types' => '',
]);
Choice
Select
$builder
->addSelect('select_field', [
'label' => 'Select Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'choices' => [],
'default_value' => [],
'allow_null' => 0,
'multiple' => 0,
'ui' => 0,
'ajax' => 0,
'return_format' => 'value',
'placeholder' => '',
]);
Checkbox
$builder
->addCheckbox('checkbox_field', [
'label' => 'Checkbox Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'choices' => [],
'allow_custom' => 0,
'save_custom' => 0,
'default_value' => [],
'layout' => 'vertical',
'toggle' => 0,
'return_format' => 'value',
]);
Radio
$builder
->addRadio('radio_field', [
'label' => 'Radio Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'choices' => [],
'allow_null' => 0,
'other_choice' => 0,
'save_other_choice' => 0,
'default_value' => '',
'layout' => 'vertical',
'return_format' => 'value',
]);
Button Group
$builder
->addButtonGroup('button_group_field', [
'label' => 'Button Group Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'choices' => [],
'allow_null' => 0,
'default_value' => '',
'layout' => 'horizontal',
'return_format' => 'value',
]);
True / False
$builder
->addTrueFalse('truefalse_field', [
'label' => 'True / False Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'message' => '',
'default_value' => 0,
'ui' => 0,
'ui_on_text' => '',
'ui_off_text' => '',
]);
Relational
Link
$builder
->addLink('link_field', [
'label' => 'Link Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'return_format' => 'array',
]);
Post Object
$builder
->addPostObject('post_object_field', [
'label' => 'Post Object Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'post_type' => [],
'taxonomy' => [],
'allow_null' => 0,
'multiple' => 0,
'return_format' => 'object',
'ui' => 1,
]);
Page Link
$builder
->addPageLink('page_link_field', [
'label' => 'Page Link Field',
'type' => 'page_link',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'post_type' => [],
'taxonomy' => [],
'allow_null' => 0,
'allow_archives' => 1,
'multiple' => 0,
]);
Relationship
$builder
->addRelationship('relationship_field', [
'label' => 'Relationship Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'post_type' => [],
'taxonomy' => [],
'filters' => [
0 => 'search',
1 => 'post_type',
2 => 'taxonomy',
],
'elements' => '',
'min' => '',
'max' => '',
'return_format' => 'object',
]);
Taxonomy
$builder
->addTaxonomy('taxonomy_field', [
'label' => 'Taxonomy Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'taxonomy' => 'category',
'field_type' => 'checkbox',
'allow_null' => 0,
'add_term' => 1,
'save_terms' => 0,
'load_terms' => 0,
'return_format' => 'id',
'multiple' => 0,
]);
User
$builder
->addUser('user_field', [
'label' => 'User Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'role' => '',
'allow_null' => 0,
'multiple' => 0,
]);
jQuery
Google Map
$builder
->addGoogleMap('google_map_field', [
'label' => 'Google Map Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'center_lat' => '',
'center_lng' => '',
'zoom' => '',
'height' => '',
]);
Date Picker
$builder
->addDatePicker('date_picker_field', [
'label' => 'Date Picker Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'display_format' => 'd/m/Y',
'return_format' => 'd/m/Y',
'first_day' => 1,
]);
Date Time Picker
$builder
->addDateTimePicker('date_time_picker_field', [
'label' => 'Date Time Picker Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
]);
Time Picker
$builder
->addTimePicker('time_picker_field', [
'label' => 'Time Picker Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'display_format' => 'g:i a',
'return_format' => 'g:i a',
'default_value' => '',
]);
Color Picker
$builder
->addColorPicker('color_picker_field', [
'label' => 'Color Picker Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'enable_opacity' => 0,
'return_format' => 'string',
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
]);
Layout
Message
$builder
->addMessage('message_field', 'message', [
'label' => 'Message Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'message' => '',
'new_lines' => 'wpautop', // 'wpautop', 'br', '' no formatting
'esc_html' => 0,
]);
Accordion
$builder
->addAccordion('accordion_field', [
'label' => 'Accordion Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'open' => 0,
'multi_expand' => 0,
'endpoint' => 0,
]);
$builder
->addAccordion('accordion_field_end')->endpoint();
Tab
$builder
->addTab('tab_field', [
'label' => 'Tab Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'default_value' => '',
'placeholder' => '',
'prepend' => '',
'append' => '',
'maxlength' => '',
'placement' => '',
]);
Group
$builder
->addGroup('group_field', [
'label' => 'Group Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'layout' => 'block'
])
->addText('sub_field')
->endGroup();
Repeater
$builder
->addRepeater('repeater_field', [
'label' => 'Repeater Field',
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'collapsed' => '',
'min' => 0,
'max' => 0,
'layout' => 'table',
'button_label' => '',
'sub_fields' => [],
]);
Flexible Content
$builder
->addFlexibleContent('flexible_content_field', [
'instructions' => '',
'required' => 0,
'conditional_logic' => [],
'wrapper' => [
'width' => '',
'class' => '',
'id' => '',
],
'button_label' => 'Add Row',
'min' => '',
'max' => '',
]);
$builder
->addLayout('layout', [
'label' => 'Layout',
'display' => 'block',
'sub_fields' => [],
'min' => '',
'max' => '',
]);
$builder
->addLayout(new FieldsBuilder());
Configuration
Composing Fields
$builder
->addFields(new FieldsBuilder());
$builder
->addField('text', 'title')
->setKey('field_title')
->setLabel('My Label')
->setDefaultValue('Lorem ipsum')
->setInstructions('This is a title.')
->setRequired()
->setUnrequired()
->setConfig('placeholder', 'Enter the title');
Composing Custom/3rd Party Addon Fields
Add any other registered custom/3rd party ACF Fields using the addField($name, $type, $args)
method.
$builder
->addFields(new FieldsBuilder());
$builder
->addField('icon', 'font-awesome')
->setLabel('My Icon')
->setInstructions('Select an icon')
->setConfig('save_format', 'class')
Modifying Fields
$builder
->modifyField('title', ['label' => 'Modified Title']);
$builder
->addFields(new FieldsBuilder())
->getField('title')
->modifyField('title', ['label' => 'Modified Title']);
Removing Fields
$builder
->removeField('title');
Field Choices
$builder
->addChoice('red')
->addChoice('blue')
->addChoice('green');
$builder
->addChoices(['red' => 'Red'], ['blue' => 'Blue'], ['green' => 'Green']);
Field Conditions
$builder
->conditional('true_false', '==', '0')
->and('true_false', '!=', '1')
->or('false_true', '==', '1');
Field Wrapper
$builder
->setWidth('30');
$builder
->setSelector('.field')
->setSelector('#field');
$builder
->setAttr('width', '30')
->setAttr('class', 'field')
->setAttr('id', 'field');
$builder
->setWrapper(['width' => '30', 'class' => 'field', 'id' => 'field']);
Field Group Location
$builder
->setLocation('post_type', '==', 'page')
->and('page_type', '==', 'front_page');
Field Group Locations
- Post:
post_type
,post_type_list
,post_type_archive
,post_template
,post_status
,post_format
,post_category
,post_taxonomy
,post
- Page:
page_template
,page_type
,page_parent
,page
- User:
current_user
,current_user_role
,user_form
,user_role
- Forms:
taxonomy
,taxonomy_list
,attachment
,comment
,widget
,nav_menu
,nav_menu_item
,block
,options_page
- Custom: Official Documentation
Field Group Position
$builder = new FieldsBuilder('banner', ['position' => 'side']); // acf_after_title, normal, side