How to Create Custom Color Palettes in WordPress Gutenberg

In this tutorial you’ll learn how to create custom color palettes for WordPress Gutenberg, making your theme even more flexible.

Color palettes are collections of swatches in the editor’s sidebar which allow you to choose from predefined colors and apply them to elements on your page. There’s also a color picker tool to select whichever color you like (we’ll be removing this option):

Using these tools you can change the appearance of text, background, UI components like buttons, and much more, all from within the Gutenberg page editor. But how can you add your own colors to these palettes? And how might you limit what users are able to pick themselves? Let’s find out!

Custom Color Palettes in WordPress Gutenberg

1. Disable the Custom Color Picker

When you’re editing certain elements in the Gutenberg editor you’ll notice, underneath the defined color swatches, a Custom color option. When you click this a color picker will open, allowing you to choose any color you can possibly think of.

As a theme developer this is a dangerous option to give users! Allowing this kind of stylistic freedom can result in the website content going way beyond any color schemes you’ve defined in your theme. Users may pick colors that clash with your theme, colors that make reading difficult (an accessibility issue), or pick a huge range of colors and ruin any continuity on the website.

• 
  Accessibility
  Accessibility Basics: Designing for Visual Impairment
  Graeme Fulton

So, for this first step, we’re going to remove this custom color picker altogether. 

Add Snippet to Your Theme’s Functions.php

Find your theme’s functions.php file. It will be in wp-content > themes > your-theme or wp-content > themes > your-child-theme.

In this example I’m using the twentytwentyone theme which comes with each new installation of WordPress at the moment. Opening up the functions.php file there’s a function called

function twenty_twenty_one_setup() {

}

Before the closing braces of that function we add the following line of code:

add_theme_support( 'disable-custom-colors' );

Note: it might well be that your functions.php doesn’t have this kind of setup function, but it’s important you place this line of code somewhere which is called by WordPress. In our case, after the setup function, there’s an add_action to do that.

add_action( 'after_setup_theme', 'twenty_twenty_one_setup' );

That’s it! If you go back to the Gutenberg editor and hit refresh, you’ll see that Custom color option has been removed.

2. Define Your Own Color Palette

To add our own colors to the available palettes we go back to our functions.php.

Back in Functions.php

In the same function we were using before, above the snippet where we disable the custom color picker, we can create an array of color values.

Again, in the twentytwentyone theme, we’ll can already see a bunch of defined colors within the twenty_twenty_one_setup() function. They’re defined in another function which looks like:

add_theme_support( 'editor-color-palette', array );

The array here is the array of colors, and each color is itself defined with an array of name:value pairs. Here’s what the existing code in twentytwentyone looks like:

    	add_theme_support(
			'editor-color-palette',
			array(
				array(
					'name'  => esc_html__( 'Black', 'twentytwentyone' ),
					'slug'  => 'black',
					'color' => $black,
				),
				array(
					'name'  => esc_html__( 'Dark gray', 'twentytwentyone' ),
					'slug'  => 'dark-gray',
					'color' => $dark_gray,
				),
                
                ... more colors
                
            )
        );

Color Arrays

For each color you want to have in your palette you’d add an array to this structure. Each array has:

• name: the name you want to call your color, a human-readable label (include text domain for proper translation)
• slug: how it’s referred within the CSS code (more on this in a moment)
• color: the actual color hex value

In the example above you’ll notice the color values are using a PHP variable (eg: $dark_gray). This isn’t compulsory, but you may find it makes sense to define your colors in variables, in case they’re used elsewhere in your code. The twentytwentyone theme uses a collection of variables like this:

// Editor color palette.
    	$black     = '#000000';
		$dark_gray = '#28303D';
		$gray      = '#39414D';
		$green     = '#D1E4DD';
		$blue      = '#D1DFE4';
		$purple    = '#D1D1E4';
		$red       = '#E4D1D1';
		$orange    = '#E4DAD1';
		$yellow    = '#EEEADD';
		$white     = '#FFFFFF';

Let’s Add Our Own Color

Let’s add our own by first defining a color variable (this is a deep red color):

$adicustom = #b11938

Then we’ll add an array to the existing list (in your case you may have had to write the editor-color-palette function yourself):

array(
	'name'  => esc_html__( 'Adi Custom', 'twentytwentyone' ),
	'slug'  => 'adicustom',
	'color' => $adicustom,
),

Now, if you refresh the Gutenberg editor, you’ll see a color swatch has been added to the palette (both text colors and background colors) and you can use it on your content!

Mission accomplished! Well, not quite.

3. Write the Corresponding CSS

You can use the color in your content on the back end, in the Gutenberg editor, but you won’t see it on the front end. This is because we now have to create a CSS rule to reflect it.

For example, if you go ahead and apply the “Adi Custom” color to some text, save it, then hit refresh on the front end, you won’t see any change. But if you inspect the code you’ll see a new class has been applied to the text you changed:

<p class="has-adicustom-color has-text-color"></p>

You’ll recognize the slug adicustom in amongst that class name, so all we have to do is define a couple of rules using that selector. We need to define one for when text color is used, and another for when background color is used, so we do that in our theme’s style.css file. For example:

.has-adicustom-color {
    color: #b11938;
}

.has-adicustom-background-color {
    background-color: #b11938;
}

For an extra layer of control you may want to use custom CSS variables for this step. Check out my short course to learn all about them!

Key Takeaways

And we’re done! That simple trick will give you, as a theme developer, a little more control over how your theme is used. Let’s go over what we learned:

1. Limiting the available colors in Gutenberg allows you to stay within branding guidelines and avoids accessibility issues.
2. Disable the custom color picker and define your new palette within your theme’s functions.php file.
3. Remember to write the corresponding CSS for the new colors inside your theme’s style.css file.

More WordPress Gutenberg Tutorials

• 
  WordPress
  What Is WordPress Gutenberg?
  Kyle Sloka-Frey
• 
  WordPress Gutenberg
  WordPress Gutenberg Editor: Quick Start Tutorial
  Kezz Bracey
• 
  WordPress Gutenberg
  The Best WordPress Gutenberg Themes for 2021, Available Now (Free & Premium)
  Tomas Laurinavicius
• 
  WordPress Gutenberg
  How to Create Custom Blocks for Gutenberg
  Adi Purdila
• 
  WordPress Gutenberg
  How to Use the WordPress Gutenberg Cover Block
  Eric Karkovack