Clone

Documentation Field Types Clone

Overview

The Clone field allows you to select and display existing fields. It does not duplicate any fields in the database. Instead, it loads and displays the selected fields at run time.

You may also select one (or more) field groups, making it possible to load in “module” groups. A good example of this can be seen in the demo video below, where a single field group is created for “Button” information. This field group is then cloned when a button is needed.

The Clone field may be used in one of two ways. It can replace itself with the selected fields (seamless) or display the selected fields as a group of sub fields.

Demo

For more, please see our tutorial on how to use the Clone field.

Changelog

• Added in version 5.4.0

Settings

Template Usage

Loading the value of a cloned field is the same as loading a normal field. If using the “Group” display setting, you may also load all cloned values as an array by loading the Clone field itself.

Some of the following examples use a Clone field called “main_button,” which is cloning a field group called “Button.” The Button field group contains 2 fields called “text” and “url.”

Basic

This example shows how to load a Clone field value with the following default settings. Note that these settings will essentially replace the Clone field with the selected fields:

• Name: main_button
• Display: seamless
• Prefix Names: no
• Fields: A field group called “Button”, as described above

<?php 
    
$text = get_field('text');
$url = get_field('url');

?>

Prefix field names

This example shows how to load a Clone field value with the following “Group” settings. Note that these settings will render the “button” fields within a group and prefix the field names. All values will be saved and loaded with the name prefix main_button_.

• Name: main_button
• Display: group
• Prefix Names: yes
• Fields: A field group called “Button”, as described above

<?php 

$text = get_field('main_button_text');
$url = get_field('main_button_url');

?>

Using the “Group” display setting will allow ACF to load the cloned field values as an array, like so:

<?php 

$button = get_field('main_button');

$text = $button['text'];
$url = $button['url'];

?>

Sub fields

Clone fields may also be used within a Repeater or Flexible Content field. This example shows the same “main_button” Clone field from the previous example, but this time used within a Repeater field.

<?php 

if( have_rows('slides') ) {
    
    while( have_rows('slides') ) {
        
        // increment row
        the_row();
        
        
        // vars
        $button = get_sub_field('button');
        
        
        // ...
        
    }
    
}

?>

Limitations

The Clone field has a few limitations. These limitations are found in edge cases when using Clone fields within Repeater or Flexible Content fields.

Multiple cloned sub fields

A cloned sub field may not be able to save its value if it exists alongside another instance of itself. For example, imagine a Repeater field called “Row” containing 2 Clone fields, both cloning in the same field, called “Cell”. Even if both Clone fields use the “Prefix Name” setting to make each “Cell” have a unique name, they both use the same field_key, so they will override each other during save.

Using the have_rows() function with a nested Clone field

The have_rows() function will return false when loading a cloned sub field using the “Group” display setting and layout set to “Block”. Please note that using the “Seamless” display setting will allow sub have_rows() loops to work as expected.

Notes

Data structure

The Clone field does not change the data structure when saving values to the database. The only change comes from the “Prefix Field Names” setting. Values are not saved as an array, but are saved as normal individual field values. This means that meta queries are possible as usual.

Data conflicts

It is possible to create data conflicts by cloning a field with a name already used in the group. This is the same issue as creating 2 fields using the same name. Please use the “Prefix Field Names” setting when appropriate to avoid this.

A good rule of thumb is to use the “Prefix Field Names” setting when choosing the “Group” display setting, and the opposite when using the “Seamless” display setting.

Disabled field groups

It is possible to clone a field group that is set to “Disabled”. Disabling a field group prevents it from being loaded on a post edit page, which is a good idea when making module groups.

Cloning a clone

It is possible to clone a Clone field. This may sound extreme, but it can be a useful feature in specific scenarios. For example, you may be creating a page builder with the Flexible Content field and find that each layout contains the same “settings” fields. Instead of duplicating these fields in each layout (and the headache of maintaining changes to these fields across multiple layouts), you could define all “settings” fields in the first layout only. The second layout could use a Clone field to clone these “settings” fields. The third layout could use a Clone field to clone the one defined in the second layout.

The benefit of this is that if you add a new “setting” to the first layout, you only need to update the Clone field in your second layout. All other Clone fields (in layout 3, 4, etc.) will mimic this and show the new “settings” field!