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 this blog post from Otto to learn the basics of how to use the WordPress customizer and then 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' );

You will be able to find examples on how to use our fields with the default WordPress Customizer API in the fields themselves (use the sidebar menu to access them). Please note that not all of them have been documented yet, this is still a work in progress.

===========================================

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',
) );

===========================================

Please keep in mind that if you do work using the default WordPress customizer API, then you will not be able to take advantage of some of Kirki's more advanced features like automatic CSS output & calculations as well as automatic postMessage script generation. These features will only be available if you use the 2nd or 3rd method of adding your own fields.