Fields

Kirki allows you to choose what kind of syntax you want to use. The way you write your code and add your fields to the customizer can vary depending on your project and your personal preferences.

There are 3 implementations you can use:

1. The default WordPress Customizer API.
2. An array of arrays
3. Static method calls

The default WordPress Customizer syntax is one of the most versatile ways to use the Customizer. You should already be familiar with it and if you're not then we strongly advise you to read the Customizer Handbook on [developer.wordpress.org before you decide you want to work with Kirki.

Example: adding a few fields using the WordPress Customizer API:

function my_custom_text_settings( $wp_customize ) {

	// Register the settings
	$wp_customize->add_setting( 'my_setting', array(
		'default'        => 'some-default-value',
		'type'           => 'theme_mod',
		'capability'     => 'edit_theme_options',
	) );

	$wp_customize->add_setting( 'my_setting_2', array(
		'default'        => 'some-default-value',
		'type'           => 'theme_mod',
		'capability'     => 'edit_theme_options',
	) );

	// Add the controls
	$wp_customize->add_control( 'my_setting', array(
		'label'       => __( 'My custom control', 'translation_domain' ),
		'section'     => 'my_section',
		'settings'    => 'my_setting',
		'type'        => 'text',
		'priority'    => 10
    ) );

	$wp_customize->add_control( 'my_setting_2', array(
		'label'       => __( 'My custom control 2', 'translation_domain' ),
		'section'     => 'my_section',
		'settings'    => 'my_setting_2',
		'type'        => 'text',
		'priority'    => 20
    ) );
}
add_action( 'customize_register', 'my_custom_text_settings' );

For some projects you may find it convenient to write your fields in the form of an array of arrays. This array can then be hooked in the kirki/fields filter and your fields will be automatically added to the customizer. This syntax is simpler than the default Customizer API for most people and still allows you to make a lot of customizations.

Example: adding the same 2 fields using the kirki/fields filter:

function my_custom_text_settings( $fields ) {

	// Add the controls
	$fields[] = array(
		'label'       => __( 'My custom control', 'translation_domain' ),
		'section'     => 'my_section',
		'settings'    => 'my_setting',
		'type'        => 'text',
		'priority'    => 10
		'options_type' => 'theme_mod',
		'capability'   => 'edit_theme_options',
	);
	
	$fields[] = array(
		'label'       => __( 'My custom control 2', 'translation_domain' ),
		'section'     => 'my_section',
		'settings'    => 'my_setting_2',
		'type'        => 'text',
		'priority'    => 20
		'options_type' => 'theme_mod',
		'capability'   => 'edit_theme_options',
	);

	return $fields;

}
add_filter( 'kirki/fields', 'my_custom_text_settings' );

In other projects you may want to add your fields using static method calls. This is the method that we find offers great flexibility and potential without sacrificing the flexibility of the system:

Kirki::add_config( 'my_config', array(
	'options_type' => 'theme_mod',
	'capability'   => 'edit_theme_options',
) );

Kirki::add_field( 'my_config', array(
	'settings' => 'my_setting',
	'label'    => __( 'My custom control', 'translation_domain' ),
	'section'  => 'my_section',
	'type'     => 'text',
	'priority' => 10,
	'default'  => 'some-default-value',
) );

Kirki::add_field( 'my_config', array(
	'settings' => 'my_setting_2',
	'label'    => __( 'My custom control 2', 'translation_domain' ),
	'section'  => 'my_section',
	'type'     => 'text',
	'priority' => 20,
	'default'  => 'some-default-value',
) );

We recommend you read this blog post from Otto to learn the basics of how to use the WordPress customizer. and the Handbook on WordPress.org.