WordPress Customizer Repeater Control

Learn how to create a repeater control using the Kirki Customizer Framework.

Back to Controls

Returnsarray

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.

Example

Creating a repeater control where each row contains 2 textfields:

Kirki::add_field( 'theme_config_id', [
	'type'        => 'repeater',
	'label'       => esc_html__( 'Repeater Control', 'kirki' ),
	'section'     => 'section_id',
	'priority'    => 10,
	'row_label' => [
		'type'  => 'text',
		'value' => esc_html__( 'Your Custom Value', 'kirki' ),
	],
	'button_label' => esc_html__('"Add new" button label (optional) ', 'kirki' ),
	'settings'     => 'my_repeater_setting',
	'default'      => [
		[
			'link_text' => esc_html__( 'Kirki Site', 'kirki' ),
			'link_url'  => 'https://kirki.org/',
		],
		[
			'link_text' => esc_html__( 'Kirki Repository', 'kirki' ),
			'link_url'  => 'https://github.com/aristath/kirki',
		],
	],
	'fields' => [
		'link_text' => [
			'type'        => 'text',
			'label'       => esc_html__( 'Link Text', 'kirki' ),
			'description' => esc_html__( 'This will be the label for your link', 'kirki' ),
			'default'     => '',
		],
		'link_url'  => [
			'type'        => 'text',
			'label'       => esc_html__( 'Link URL', 'kirki' ),
			'description' => esc_html__( 'This will be the link URL', 'kirki' ),
			'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:

Kirki::add_field( 'theme_config_id', [
	'type'        => 'repeater',
	'label'       => esc_html__( 'Repeater Control', 'kirki' ),
	'section'     => 'section_id',
	'priority'    => 10,
	'row_label' => [
		'type'  => 'field',
		'value' => esc_html__( 'Your Custom Value', 'kirki' ),
		'field' => 'link_text',
	],
	'button_label' => esc_html__('"Add new" button label (optional) ', 'kirki' ),
	'settings'     => 'my_repeater_setting',
	'default'      => [
		[
			'link_text' => esc_html__( 'Kirki Site', 'kirki' ),
			'link_url'  => 'https://kirki.org/',
		],
		[
			'link_text' => esc_html__( 'Kirki Repository', 'kirki' ),
			'link_url'  => 'https://github.com/aristath/kirki',
		],
	],
	'fields' => [
		'link_text' => [
			'type'        => 'text',
			'label'       => esc_html__( 'Link Text', 'kirki' ),
			'description' => esc_html__( 'This will be the label for your link', 'kirki' ),
			'default'     => '',
		],
		'link_url' => [
			'type'        => 'text',
			'label'       => esc_html__( 'Link URL', 'kirki' ),
			'description' => esc_html__( 'This will be the link URL', 'kirki' ),
			'default'     => '',
		],
	]
] );

Creating a repeater control with a maximum limit of 3 rows:

Kirki::add_field( 'theme_config_id', [
	'type'        => 'repeater',
	'label'       => esc_attr__( 'Repeater Control', 'kirki' ),
	'section'     => 'section_id',
	'priority'    => 10,
	'row_label' => [
		'type'  => 'field',
		'value' => esc_html__( 'Your Custom Value.', 'kirki' ),
		'field' => 'link_text',
	],
	'settings'    => 'my_repeater_setting',
	'fields' => [
		'link_text' => [
			'type'        => 'text',
			'label'       => esc_attr__( 'Link Text', 'kirki' ),
			'description' => esc_attr__( 'This will be the label for your link', 'kirki' ),
		],
	],
	'default'     => [
		[
			'link_text' => esc_attr__( 'Link Text Example', 'kirki' ),
		],
	],
	'choices' => [
		'limit' => 3
	],
] );

Usage

<?php
// Default values for 'my_repeater_setting' theme mod.
$defaults = [
  [
    'link_text' => esc_html__( 'Kirki Site', 'kirki' ),
		'link_url'  => 'https://kirki.org/',
	],
	[
		'link_text' => esc_html__( 'Kirki Repository', 'kirki' ),
		'link_url'  => 'https://github.com/aristath/kirki',
	],
];

// Theme_mod settings to check.
$settings = get_theme_mod( 'my_repeater_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>

Can't find what you're looking for? Check the github issues or edit this page to add what's missing.