One of the many nice features of the new Gutenberg editor is the ability to easily create color palettes for your theme.
These color palettes give users the ability to easily select from a predefined set of color options in your theme.
That’s great if you’re going to limit your theme to a specific set of colors. But if you give the user options to customize their colors we need a more elegant solution.
Rich Tabor has put together an excellent article on How to Add Customizer Colors to Gutenberg Block Color Palettes. It is extremely easy to implement.
Automating Color Creation
When you add a new color option to the customizer and color palette there are several different pieces you need to add. Each color option will require the following:
- Customizer setting and control
- Gutenberg color palette support array
.has-{color-slug}-colorand.has-{color-slug}-background-colorCSS classes
That is a lot of repeatable code that needs to be duplicated if we’re adding colors one-by-one. Or we can automate things and add all our color options in one area and build out everything else.
Step 1: Creating a Color Option Array
The first thing we’ll need to do is create an array to store all of our options for each color we’ll be adding. This will be the source for all color information.
$gibby_color_options = array(
array(
'name' => esc_html__( 'Gutenberg Primary', 'gibby' ),
'description' => esc_html__( 'Describe how this color is used.', 'gibby' ),
'slug' => 'gibby-primary',
'option' => 'gibby_primary_color',
'default' => '#bada55', // 🤘
'transport' => 'postMessage',
),
);namewill be the name for the color in the customizer and Gutenberg color palette.descriptionis optional for giving more information about he color in the customizer.slugshould be unique for the color and is used to generate the CSS classes used by the Gutenberg color palette.optionis the unique key for the color in the customizer.defaultis the default color for the customizer and block color palette.transportis used for the customizer.postMessageallows for live updating of the color in the customizer through JavaScript.refreshcan be used to refresh the page when updating the color in the customizer.
Step 2: Create A Color Palette Array
When adding theme support for Gutenberg’s color palettes you need to output an array of each color’s name, slug, and color.
In order to easily do this we’ll use the $gibby_color_options array to create another array to be used in the add_theme_support( 'editor-color-palette' ); function.
/**
* Build out the Gutenberg color palette to be used in add_theme_support( 'editor-color-palette' );
*/
$gibby_color_palette = array();
foreach ( $gibby_color_options as $color ) {
$gibby_color_palette[] = array(
'name' => $color['name'],
'slug' => $color['slug'],
'color' => esc_html( get_theme_mod( $color['option'], $color['default'] ) ),
);
}First, we create the $gibby_color_palette array to store the individual color arrays to be used in the add_theme_support function.
Next, the foreach loop runs through the $gibby_color_options from step 1 and outputs the name and slug of each option.
The color argument is a little more complex. It uses get_theme_mod() to get the value that’s been set in the customizer ($color['option']). If a value hasn’t been set it falls back to the default color. And we sanitize everything per best practices with esc_html().
Step 3: Add Theme Support
The next step is to implement the colors in the Gutenberg color palette using the add_theme_support function. This should be hooked into the after_setup_theme action.
function gibby_setup() {
add_theme_support( 'editor-color-palette', $gibby_color_palette );
}
add_action( 'after_setup_theme', 'gibby_setup' );All we’re doing here is passing $gibby_color_palette from step 2 into as the second parameter to the add_theme_support() function.
This enables the colors in the Gutenberg color palette. But we’ll still need a few more steps to get everything connected.
Step 4: Adding Customizer Controls
Next up we’ll add controls to the customizer for setting our colors.
We’re going create a function to take our $gibby_color_options array and loop through each color with a foreach to create the customizer settings and controls.
We’ll then take our newly created function and hook it into the customize_register action.
/**
* Add postMessage support for site title and description for the Theme Customizer.
*
* @param WP_Customize_Manager $wp_customize Theme Customizer object.
*/
function gibby_customize_register( $wp_customize ) {
/**
* Set custom theme colors
*/
foreach ( $gibby_color_options as $color ) {
$wp_customize->add_setting(
$color['option'], array(
'default' => $color['default'],
'sanitize_callback' => 'sanitize_hex_color',
'transport' => $color['transport'],
)
);
$wp_customize->add_control(
new WP_Customize_Color_Control(
$wp_customize, $color['option'], array(
'label' => $color['name'],
'description' => $color['description'],
'section' => 'colors',
)
)
);
}
}
add_action( 'customize_register', 'gibby_customize_register' );Inside the foreach loop we’re using the $wp_customize->add_setting to create the customizer setting to store our value. This stores the theme mod as the$gibby_color_options['option'] defined in step 1.
$wp_customize->add_control sets up the actual color picker in the customizer using WP_Customize_Color_Control.
Step 5: Live Updating Colors in the Customizer
Next up we’re going to need to pass the $gibby_color_options from PHP to JavaScript so we can build out the customizer preview JS.
In order to do this we’ll need a customizer.js file. Then we’ll need to enqueue that file and pass the PHP array to JS using wp_localize_script.
First the code.
/**
* Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
*/
function gibby_customize_preview_js() {
wp_enqueue_script( 'gibby-customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '20151215', true );
wp_localize_script( 'gibby-customizer', 'gibby_color_options_js', array(
'colorOptions' => json_encode( $gibby_color_options ),
)
);
}
add_action( 'customize_preview_init', 'gibby_customize_preview_js' );Customizer JavaScript files are enqueued on the customize_preview_init action hook. So we’ll need to create a function to connect to that hook. In the example above that’s gibby_customize_preview_js.
Then we’re going to enqueue the new customizer.js file we created with the $handle of gibby-customizer. We’ll do so using the wp_enqueue_script function.
The wp_localize_script() takes 3 parameters. The $handle of the script we want to localize. The $name of the variable to access the data in JavaScript. And, finally, the $data to be passed from PHP to JavaScript. In our case that’ll be our $gibby_color_options.
In order to prepare the data we’re using json_encode and passing it as an array with the key $colorOptions.
Step 6: Creating Color CSS Classes
We’re getting closer. But now we need to setup the CSS classes that are used by Gutenberg when setting text colors or background colors via the color palette.
These break down to .has-{color-slug}-color and .has-{color-slug}-background-color. With {color-slug} being the slug set in the $gibby_color_options array from step 1.
Again we’re going to create a function to loop through the $gibby_color_options array and output the needed CSS classes.
/**
* Add custom colors to Gutenberg.
*/
function gibby_gutenberg_colors() {
// If we don't have any color options set don't add any CSS
if ( empty( $gibby_color_options ) ) {
return;
}
$css = '';
foreach ( $gibby_color_options as $color ) {
$custom_color = get_theme_mod( $color['option'], $color['default'] );
$css .= '.has-' . $color['slug'] . '-color { color: ' . esc_attr( $custom_color ) . ' !important; }';
$css .= '.has-' . $color['slug'] . '-background-color { background-color: ' . esc_attr( $custom_color ) . '; }';
}
return wp_strip_all_tags( $css );
}First we’re checking to make sure there are actually color options set that we need to create CSS for. If there are we’re initializing $css as a blank string.
Next up is our foreach loop that uses get_theme_mod to store the color as set in the cusomtizer or the default color as $custom_color.
We then append the custom CSS classes for each color option into the $css variable and return it while stripping all HTML tags using wp_strip_all_tags.
Now let’s pull it into the editor and theme.
Step 7: Enqueuing the CSS
Now we need to add the CSS into the site on the Gutenberg editor and the frontend. We’ll do so by using the wp_add_inline_style to connect to our editor styles and our frontend styles. Check here if you need to refresh on enqueueing scripts and styles for Gutenberg.
First up, we’ll need to make sure we have styles enqueued on the frontend and for the Gutenberg editor. Make note of the handles for these scripts as we’ll be using them in the wp_add_inline_style function.
/**
* Enqueue scripts and styles.
*/
function gibby_scripts() {
wp_enqueue_style( 'gibby-style', get_stylesheet_uri() );
}
add_action( 'wp_enqueue_scripts', 'gibby_scripts' );
/**
* Enqueue block editor style
*/
function gibby_block_editor_styles() {
wp_enqueue_style( 'gibby-editor-styles', get_theme_file_uri( '/css/style-editor.css' ), false, '1.0', 'all' );
}
add_action( 'enqueue_block_editor_assets', 'gibby_block_editor_styles' );Next, we’ll actually call the function creating the CSS classes in step 6 to add the styles inline after the above scripts are enqueued.
/**
* Enqueue theme colors within Gutenberg.
*/
function gibby_gutenberg_styles() {
// Add custom colors to Gutenberg.
wp_add_inline_style( 'gibby-editor-styles', gibby_gutenberg_colors() );
}
add_action( 'enqueue_block_editor_assets', 'gibby_gutenberg_styles' );
/**
* Enqueue theme colors.
*/
function gibby_styles() {
// Add custom colors to the front end.
wp_add_inline_style( 'gibby-style', gibby_gutenberg_colors() );
}
add_action( 'wp_enqueue_scripts', 'gibby_styles' );Wrapping Up
There you have it. That will have you up and running with colors added to the customizer and Gutenberg color palette. You’ll then be able to update colors in the customizer and see this reflected in the available colors in the Gutenberg color palette.
If you’re wanting to get started even faster I’ve built this into the Gutenberg starter theme, gibby. Named after St. Louis Cardinals Hall of Fame starter Bob Gibson.
It’s built off _s by Automattic with the addition of styles for core Gutenberg blocks and the above color palette integrations. So all you need to do is add to the $gibby_color_options array in inc/color-palette.php and you’ll be off and running.
