Are you a theme author? Checkout new Kirki Helpers for your themes, or start something new using our _s fork as a starting point!

repeater

returnsarray

Description

Improve this section

Repeater controls allow you to build repeatable blocks of fields. You can create for example a set of fields that will contain a checkbox and a textfield. The user will then be able to add “rows”, and each row will contain a checkbox and a textfield.


Examples

Improve this section

Creating a repeater control where each row contains 2 textfields:

<?php
Kirki::add_field( 'my_config', array(
	'type'        => 'repeater',
	'label'       => esc_attr__( 'Repeater Control', 'my_textdomain' ),
	'section'     => 'my_section',
	'priority'    => 10,
	'row_label' => array(
		'type' => 'text',
		'value' => esc_attr__('your custom value', 'my_textdomain' ),
	),
	'settings'    => 'my_setting',
	'default'     => array(
		array(
			'link_text' => esc_attr__( 'Kirki Site', 'my_textdomain' ),
			'link_url'  => 'https://aristath.github.io/kirki/',
		),
		array(
			'link_text' => esc_attr__( 'Kirki Repository', 'my_textdomain' ),
			'link_url'  => 'https://github.com/aristath/kirki',
		),
	),
	'fields' => array(
		'link_text' => array(
			'type'        => 'text',
			'label'       => esc_attr__( 'Link Text', 'my_textdomain' ),
			'description' => esc_attr__( 'This will be the label for your link', 'my_textdomain' ),
			'default'     => '',
		),
		'link_url' => array(
			'type'        => 'text',
			'label'       => esc_attr__( 'Link URL', 'my_textdomain' ),
			'description' => esc_attr__( 'This will be the link URL', 'my_textdomain' ),
			'default'     => '',
		),
	)
) );
?>

Creating a repeater control where the label has a dynamic name based on a field’s input. This will use ['row_label']['value'] if nothing is returned from the specified field:

<?php
Kirki::add_field( 'my_config', array(
	'type'        => 'repeater',
	'label'       => esc_attr__( 'Repeater Control', 'my_textdomain' ),
	'section'     => 'my_section',
	'priority'    => 10,
	'row_label' => array(
		'type'  => 'field',
		'value' => esc_attr__('your custom value', 'my_textdomain' ),
		'field' => 'link_text',
	),
	'settings'    => 'my_setting',
	'default'     => array(
		array(
			'link_text' => esc_attr__( 'Kirki Site', 'my_textdomain' ),
			'link_url'  => 'https://aristath.github.io/kirki/',
		),
		array(
			'link_text' => esc_attr__( 'Kirki Repository', 'my_textdomain' ),
			'link_url'  => 'https://github.com/aristath/kirki',
		),
	),
	'fields' => array(
		'link_text' => array(
			'type'        => 'text',
			'label'       => esc_attr__( 'Link Text', 'my_textdomain' ),
			'description' => esc_attr__( 'This will be the label for your link', 'my_textdomain' ),
			'default'     => '',
		),
		'link_url' => array(
			'type'        => 'text',
			'label'       => esc_attr__( 'Link URL', 'my_textdomain' ),
			'description' => esc_attr__( 'This will be the link URL', 'my_textdomain' ),
			'default'     => '',
		),
	)
) );
?>

Usage

Improve this section
Please note: in all our examples we're assuming you're using theme_mods. If in your Project's Configuration you've chosen to use options instead of theme_mods, then please refer to the Getting Values documentation.
<?php
// Default values for 'my_setting' theme mod.
$defaults = array(
    array(
        'link_text' => esc_attr__( 'Kirki Site', 'my_textdomain' ),
		'link_url'  => 'https://aristath.github.io/kirki/',
	),
	array(
		'link_text' => esc_attr__( 'Kirki Repository', 'my_textdomain' ),
		'link_url'  => 'https://github.com/aristath/kirki',
	),
);

// Theme_mod settings to check.
$settings = get_theme_mod( 'my_setting', $defaults ); ?>

<div class="kirki-links">
    <?php foreach( $settings as $setting ) : ?>
        <a href="<?php $setting['link_url']; ?>">
            <?php $setting['link_text']; ?>
        </a>
    <?php endforeach; ?>
</div>

Arguments

Argument Required Type Description
type yes string Set to repeater.
default no array Use the key of one of the items in the choices argument.
fields yes array Define an array of fields that will be used. Each defined field must be an array.
row_label no array An array of settings for the display of each row produced by the repeater control.
row_label['type'] no string Accepts `field` or `text` for type. Defaults to `text` if not specified.
row_label['value'] no string When `row_label['type']` is set to `'text'` this is the text that appears in the label of each row. Defaults to `'row'` if not specified. Each row is appended with a number to represent it's instance. If `row_label['type']` is set to `'field'` this will be the default text used if value is obtained from the specified field.
row_label['field'] no string Accepts a field that is specifed in fields for the repeater control. The field's value will be displayed as the row label, or default to the `row_label['value']` (used also for new rows).
settings yes string The setting-name that will be used to identify this field.
section yes string Defines the section in which this field's control will be added.
label no string The title that will be displayed in the control.
description no string An optional description
priority no int You can use priority to change the order in which your controls are added inside a section. Defaults to 10.
variables no array If you're using a compiler you can use this to define the corresponding variable names. See variables documentation for more details.
tooltip no string Add a localized string to show an informative tooltip.
active_callback no string/array A callable function or method returning boolean (true/false) to define if the current field will be displayed or not. Overrides the required argument if one is defined.
sanitize_callback no string/array Not necessary since we already have a default sanitization callback in pace. If you want to override the default sanitization you can enter a callable function or method.
transport no string refresh or postMessage. defaults to refresh.
required no array Define field dependencies if you want to show or hide this field conditionally based on the values of other controls.
capability no string The capability required so that users can access this setting. This is automatically set by your configuration, and if none is defined in your config then falls-back to edit_theme_options. You can use this to override your config defaults on a per-field basis.
option_type no string theme_mod, option, user_meta. This option is set in your configuration but can be overridden on a per-field basis. See configuration documentation for more details.
option_name no string This option is set in your configuration but can be overridden on a per-field basis. See configuration documentation for more details.
output no array Define an array of elements & properties to auto-generate and apply the CSS to your frontend. See output documentation for more details.
js_vars no array Define an array of elements & properties to auto-generate and apply the necessary JS in order for postMessage to work. Requires that transport is set to postMessage.

The following docs are for Kirki 2.2.0 and above.