README

This control extends control-react-colorful.

kirki-framework/control-color

Installation

To install this package use composer:

composer require kirki-framework/control-color:dev-nightly

NOTE: If you get errors with the package dependencies, please run the following first:

composer require kirki-framework/control-react-colorful:dev-nightly

Until Kirki v4.0 is released some of these dependencies may not have a tag released, so in the meantime the above will allow you to install and use everything. new \Kirki\Field\Color( [ 'settings' => 'my_control_setting_id', 'label' => esc_html__( 'My Color Control', 'textdomain' ), 'description' => esc_html__( 'A description here.', 'kirki' ), 'section' => 'my_section_id', 'default' => '#ff0000', 'choices' => [ 'alpha' => true, ], ] );

Usage

This package contains the control itself, as well as a simplified API for the WordPress Customizer, installed via the composer dependencies system.

Using the simplified API

new \Kirki\Field\Color(
	[
		'settings'    => 'my_control_setting_id',
		'label'       => esc_html__( 'My Color Control', 'textdomain' ),
		'description' => esc_html__( 'A description here.', 'kirki' ),
		'section'     => 'my_section_id',
		'default'     => '#ff0000',
		'choices'     => [
			'alpha' => true,
		],
	]
);

Using the Customizer API

/**
 * Register customizer settings and controls.
 *
 * @param \WP_Customize_Manager $wp_customize The Customizer object.
 */
function my_customize_register_function( $wp_customize ) {

	// Add setting.
	$wp_customize->add_setting(
		'my_control_setting_id',
		[
			'type'              => 'theme_mod',
			'capability'        => 'edit_theme_options',
			'default'           => '#0000ff',
			'transport'         => 'refresh', // Or 'postMessage'.
			'sanitize_callback' => [ '\Kirki\Field\ReactColorful', 'sanitize' ],
		]
	);

	// Add control.
	$wp_customize->add_control(
		new \Kirki\Control\Color(
			$wp_customize,
			'my_control_setting_id',
			[
				'label'       => esc_html__( 'My Color Control', 'textdomain' ),
				'description' => esc_html__( 'A description here.', 'kirki' ),
				'section'     => 'my_section_id',
				'choices'     => [
					'alpha' => true,
				],
			]
		)
	);

	// Add more settings...

	// Add more controls...

}
add_action( 'customize_register', 'my_customize_register_function' );

Arguments

mode

Likely, you'll almost never need this. The possible set for now is 'mode' => 'hue' which is to set the color picker to use the hue (only) mode.

choices

The choices argument can contain these values:

alpha (bool) — Will be ignored if form_component is defined
save_as (bool) — Will be ignored if form_component is defined
trigger_style (string)
button_text (string) — Only applied if trigger_style value is button
form_component (string) — Look at form_component choice for more detail.

Choices

alpha (bool)

The default is treated as false. If you want to show the alpha channel, then use 'alpha' => 'true' in inside choices argument. For example:

'choices' => [
	'alpha' => true
]

This alpha choice will be ignored if you define form_component inside choices argument.

save_as (string)

This is a new choice start from v4. Accepts 'string' (default) or 'array'. If you want to save the value as array, you can use 'save_as' => 'array'.

Example of usage:

'choices' => [
	'save_as' => 'array'
]

Example of result:

[
	'r' => 255,
	'g' => 255,
	'b' => 50,
	'a' => '0.7'
]

This save_as choice will be ignored if you define form_component inside choices argument.

trigger_style (string)

This trigger_style choice default value is input. If you want to use button as the trigger, set the trigger_style choice to button. Usage example:

'choices' => [
	'trigger_type' => 'button'
]

button_text (string)

This button_text choice will only be implemented if trigger_syle value is button.
Usage example:

'choices' => [
	'trigger_type' => 'button',
	'button_text'  => 'Select Color'
]

form_component

You can pass arguments to the react-colorful component using the choices argument in the control. The only required argument here is form_component.

And in the form_component argument you can define the type of control you want, using one of the the following:

HexColorPicker
RgbColorPicker
RgbStringColorPicker
RgbaColorPicker
RgbaStringColorPicker
HslColorPicker
HslStringColorPicker
HslaColorPicker
HslaStringColorPicker
HsvColorPicker
HsvStringColorPicker
HsvaColorPicker
HsvaStringColorPicker

Their value will be saved either as an array or as a string in database (depends on form_component value). For information about the arguments you can use, please refer to the react-colorful documentation.

Development

If you want to make changes to this control, you can edit the JS files in the src folder.

If you haven't installed the packages, then run npm install
After done editing, run npm run build

License

MIT License

kirki-framework / control-color

Maintainers

Details