The ultimate guide to WordPress color palettes

While there is no shortage of articles published about adding general support for a theme’s color palette within the Gutenberg editor, I’m going to focus on the color class changes deployed in Gutenberg 2.8.

Gutenberg includes a default color palette component for blocks to utilize, although it’s relatively easy for a WordPress theme to provide a more suitable palette to empower users.

Add support for color palettes

To add color palettes to the block editor, the first step is to add a call to add_theme_support in a WordPress theme’s functions.php file, referencing the editor-color-palette feature. Next, hook it in via after_theme_setup.

* Add support for custom color palettes in Gutenberg.
function tabor_gutenberg_color_palette() {
'editor-color-palette', array(
'name' => esc_html__( 'Black', '@@textdomain' ),
'slug' => 'black',
'color' => '#2a2a2a',
'name' => esc_html__( 'Gray', '@@textdomain' ),
'slug' => 'gray',
'color' => '#727477',
add_action( 'after_setup_theme', 'tabor_gutenberg_color_palette' );

If you’re familiar with WordPress theme development, this is no different than any other opt-in feature that WordPress themes may support. Below you’ll find an example of how WordPress themes may add support for custom Gutenberg color palettes, and how I’ve deployed them within Tabor:

The two colors, black and gray, will be shown in the order they are added, as pictured in the screenshot below.

It’s also important to note that while there is no limit to how many colors can be defined, don’t go overboard. The point is to make a clear and cohesive color palette that will empower users, not confuse them.

If you’ve already updated your WordPress theme with a custom Gutenberg color palette, you’ve probably noticed a few slight differences in the example above from what you’ve deployed. Here’s how WordPress theme developers previously added custom color palettes, prior to Gutenberg 2.8—and consequently, what needs updating:

// Adds support for editor color palette.
add_theme_support( 'editor-color-palette',

Gutenberg 2.8 introduces support for color classes, which allow colors to be assigned via classes, instead of inline styling. The new functionality makes total sense, albeit making custom palettes slightly more difficult to implement.

So let’s add support for our new color classes.

Add support for color classes

Adding the actual color palette is only the first step for WordPress themes to fully support custom color palettes.

Now that themes are responsible for establishing the styling associated with custom colors, developers are required to add all contextual style classes for each custom color added via the add_theme_support( 'editor-color-palette' ) function.

Referring back to the tabor_gutenberg_color_palette() example function above, I’ve added support for our two custom colors, black and gray. We’ll need to add appropriate color classes for those colors within the WordPress theme’s primary stylesheet and the theme’s Gutenberg stylesheet.

For reference, core blocks use color and background-color contexts, so we’ll do the same. The color class is defined with has appended to the color, followed by the color name using kebab case and ending with the context:

.has-black-background-color {
background-color: #2a2a2a;
.has-black-color {
background-color: #2a2a2a;
.has-gray-background-color {
background-color: #7a7a7a;
.has-gray-color {
color: #7a7a7a;

Again, these color classes should be added to your theme’s primary stylesheet, as well as within Gutenberg, so that color selections are established on the front end and previewed in real-time within the editor.

I recently published a primer, covering how to add WordPress theme styles to Gutenberg, if you need a refresher.

Now that we’ve added the custom colors to Gutenberg via add_theme_support( 'editor-color-palette' ), created color classes with appropriate contexts to reference our colors, and loaded those classes into Gutenberg, your theme’s custom color palettes should be good to go. When a user selects the gray color for a text color option from Gutenberg’s color palette, the .has-gray-color class is added to the corresponding element, therefore setting the color attribute to #7a7a7a. And when the user views the page on the front end, the .has-gray-color color class is assigned to that element as well, instead of an inline style.

I like where Gutenberg is headed, and I appreciate the forward-thinking approach of using utility classes instead of forcing inline styling everywhere. Sure, it’s a bit more comprehensive for WordPress theme developers and Gutenberg block developers, though at the end of the day, color classes are much more sustainable — and cleaner.


  1. Simba Avatar

    I really appreciate this guide. Thanks!

  2. Edison Avatar

    This is great thank you. What about setting color palettes inside blocks? How could this be set up inside of a block? I’m having trouble finding this solution.

    1. Rich Tabor Avatar

      You’ll need to add a ColorPalette component, like I did here on CoBlocks.

      1. Edison Avatar

        Thank you for your help, but I meant setting preset colors inside of the block. Like so:

        How could I make this work? I would like different preset colors for different components declared inside the block.
        Thank you so much for your help.

      2. Rich Tabor Avatar

        Are you saying that you’d like separate default colors for different blocks? You can set them defaults via the actual component, though not specifically for multiple core blocks – at least not that I know of. That’s not something I’ve played around with, though it’s an interesting idea.

      3. Edison Avatar

        Sorry, it seems the code I wanted to include in my previous comment didn’t output. I’ll try again here and I’m also including a link to the idea. This used to work before but doesn’t seem to work with the latest Gutenberg version.

  3. Jeff Esterby Avatar

    The first example breaks in later versions of Gutenberg (~3.4.0) – in order to fix it you need to wrap the custom color arrays into a main array like so:

    ‘editor-color-palette’, array(
    ‘name’ => esc_html__( ‘Black’, ‘@@textdomain’ ),
    ‘slug’ => ‘black’,
    ‘color’ => ‘#2a2a2a’,
    ‘name’ => esc_html__( ‘Gray’, ‘@@textdomain’ ),
    ‘slug’ => ‘gray’,
    ‘color’ => ‘#727477’,

    1. Rich Tabor Avatar

      Good catch! Fixed!

  4. Sébastien Dumont Avatar

    Is it possible to change the color selections for our own made blocks?

    1. Rich Tabor Avatar

      Hey Séb, do you mean having a block override the color values present within that one block? If so, I’m not sure?

      1. Andrea Barghigiani Avatar

        Hi Rich,
        I need to customize the colors of a block. In my theme I’ve already added the color that I need and the default WordPress block are getting those but the custom block of external plugin (like CoBlocks for example) are ignoring them.

        Do you know a way to override plugin block colors?

        Thank you for the article and for the future help.

      2. Rich Tabor Avatar

        Hey Andrea, do you mind writing me at with some details? Like, how are you adding the colors?

  5. Tony Cain Avatar

    Hi, I’m wondering if I can add names to palettes this way. For example, if I have a “Primary” and “Secondary” color palette, could I separate the two with headings?

    1. Rich Tabor Avatar

      The slug value of the colors become the class names. For example, a slug of “primary” becomes, .has-primary-background-color, and .has-primary-color. 👍

  6. Kevin Donnigan Avatar

    Thanks for this tutorial. It’s perfect to help learn all customizations you can do in theme development with Gutenberg.

    1. Rich Tabor Avatar

      Glad you like it Kevin! 🤜🤛

  7. Chuck Smith Avatar

    Hey Rich
    Your subscription for has a 404 error and is not working

    1. Rich Tabor Avatar

      Hey Chuck, I’m not following?

  8. Jim Hudson Avatar

    Hi, Thanks for great tutorial. I’ve got it working except if I select a heading lock the colors don’t show up. The palette only displays on text paragraph. Anyway to enable it for headers and lists?

    1. Rich Tabor Avatar

      Hey Jim! So core blocks handle their own coloring options – so you’d need to filter the settings to add the color palette to those blocks. We did however add that functionality to the core paragraph and list blocks in CoBlocks.

  9. Jim Hudson Avatar

    Hi Rich,
    Thank you for the quick reply and tip. I’m in learning mode with blocks so I’m forgoing the plugin route until I understand the underlying code a little better, but, looks like a great plugin and one I’ll probably use someday.

  10. Anthony Tilke Avatar

    Hi Rich. Thanks for this article. Is it possible to have a separate palette for the background and text? I add theme support for custom color palettes and the colors appear duplicated under background and text. It would seem to me that support should exist to have different colors for background and text in a custom theme.

    1. Rich Tabor Avatar

      I see you point on having different background and foreground colors, but I do think having a consistent palette accessible in any color application may be a bit more practical UX wise – as you know exactly what colors are available.

  11. Tom Avatar

    Hi Rich,

    thanks for the tutorial!

    I’m wondering, if there is a way just to add some colors to the existing color palette and not replacing the original at all.
    By the way, I couldn’t figure out yet, where those values of the original palette are stored?
    Any clue
    Thank you

Leave a Reply

Your email address will not be published. Required fields are marked *