Repeater controls allow you to build repeatable blocks of fields. For example, you can create 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.

Supported Fields

The repeater can contain only a limited amount of fields.

• Text
• Select
• Checkbox
• Image
• URL
• Upload
• Dropdown Pages
• Color
• Radio
• Radio-image
• Textarea

Example

Creating a repeater control where each row contains 2 textfields, a select field & a checkbox:

new \Kirki\Field\Repeater(
	[
		'settings' => 'repeater_setting',
		'label'    => esc_html__( 'Repeater Control', 'kirki' ),
		'section'  => 'repeater_section',
		'priority' => 10,
		'default'  => [
			[
				'link_text'   => esc_html__( 'Kirki Site', 'kirki' ),
				'link_url'    => 'https://kirki.org/',
				'link_target' => '_self',
				'checkbox'    => false,
			],
			[
				'link_text'   => esc_html__( 'Kirki WP', 'kirki' ),
				'link_url'    => 'https://wordpress.org/plugins/kirki/',
				'link_target' => '_blank',
				'checkbox'    => true,
			],
		],
		'fields'   => [
			'link_text'   => [
				'type'        => 'text',
				'label'       => esc_html__( 'Link Text', 'kirki' ),
				'description' => esc_html__( 'Description', 'kirki' ),
				'default'     => '',
			],
			'link_url'    => [
				'type'        => 'text',
				'label'       => esc_html__( 'Link URL', 'kirki' ),
				'description' => esc_html__( 'Description', 'kirki' ),
				'default'     => '',
			],
			'link_target' => [
				'type'        => 'select',
				'label'       => esc_html__( 'Link Target', 'kirki' ),
				'description' => esc_html__( 'Description', 'kirki' ),
				'default'     => '_self',
				'choices'     => [
					'_blank' => esc_html__( 'New Window', 'kirki' ),
					'_self'  => esc_html__( 'Same Frame', 'kirki' ),
				],
			],
			'checkbox'    => [
				'type'    => 'checkbox',
				'label'   => esc_html__( 'Checkbox', 'kirki' ),
				'default' => false,
			],
		],
	]
);

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:

new \Kirki\Field\Repeater(
	[
		'settings'     => 'repeater_setting_2',
		'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' ),
		'default'      => [
			[
				'link_text'   => esc_html__( 'Kirki Site', 'kirki' ),
				'link_url'    => 'https://kirki.org/',
			],
			[
				'link_text'   => esc_html__( 'Kirki WP', 'kirki' ),
				'link_url'    => 'https://wordpress.org/plugins/kirki/',
			],
		],
		'fields'       => [
			'link_text'   => [
				'type'        => 'text',
				'label'       => esc_html__( 'Link Text', 'kirki' ),
				'description' => esc_html__( 'Description', 'kirki' ),
				'default'     => '',
			],
			'link_url'    => [
				'type'        => 'text',
				'label'       => esc_html__( 'Link URL', 'kirki' ),
				'description' => esc_html__( 'Description', 'kirki' ),
				'default'     => '',
			],
		],
	]
);

To limit the amount of rows, simply add the choices argument and pass a limit as shown here:

'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>