Design Customisation

Gutenberg Colour Settings: The Ultimate Guide

The Gutenberg Block Editor allows users to customise text and background colours for different blocks.

In this article, we’ll first look at what these colour settings are, and how they work. We’ll then see how to disable the custom colour picker and the default colour palette. Finally we’ll learn how to add our own custom colour palette in a theme.

What are the Gutenberg colour settings?

A screenshot of the Colour Settings panel for a paragraph block in the Gutenberg Block Editor.
Select a block that support Colour Settings to show the panel in the Block Editor sidebar.

By default, the Gutenberg Block Editor adds a setting to the following blocks to change the text and the background colour:

  • Button
  • Cover
  • Group
  • Heading
  • Paragraph
  • Table
  • Media & Text

Users can select from a set of default colour, or use a colour picker to define their own colour.

The colour picker in the Gutenberg Colour Settings panel.

How does Gutenberg add these colours to the content?

Gutenberg adds classes to the markup of a block that uses predefined colours. These class name indicates the names of the selected colour, as well as whether it applies to the text or to the background.

Here is an example of a styled paragraph block:

A Gutenberg paragraph block using a predefined colour from the default palette.

And this is the block’s HTML on the frontend:

<p class="has-text-color has-background has-very-light-gray-color has-very-dark-gray-background-color">Lorem ipsum dolor sit amet.</p>

As you can see there are generic has-text-color and has-background classes–as well as specific has-very-light-gray-color and has-very-dark-gray-background-color classes that designate the selected colours.

The WordPress Core file at wp-includes/css/dist/block-library/style.css contains the CSS styles for these classes. They are part of the the default Block Library styles.

A Gutenberg paragraph block styled using the colour picker for the background.

If the user applies a custom colour using the colour picker, an inline style is added to the paragraph tag.

<p style="background-color:#bc0000" class="has-text-color has-background has-very-light-gray-color">Lorem ipsum dolor sit amet.</p>

As an added bonus, WordPress calculates the contrast between the selected text and background colours, and warns you if the combination is difficult to read.

A screenshot of the low contrast warning in WordPress Gutenberg.

How to Disable The Gutenberg Custom Colour Picker?

To disable the custom colour picker, add the following code snippet to your theme’s function.php file:

function wpdc_disable_gutenberg_custom_colour_picker() {
	add_theme_support( 'disable-custom-colors' );
add_action( 'after_setup_theme', 'wpdc_disable_gutenberg_custom_colour_picker' );

This will remove the ability to select a custom colour, while keeping the colour palette accessible.


The Gutenberg colour settings panel with all available options.


The Gutenberg colour settings panel with the colour picker disabled.

How to Disable The Gutenberg Colour Palette?

To disable the predefined colour palette, add the following code snippet to your theme’s function.php file:

function wpdc_disable_gutenberg_custom_colour_palette() {
	add_theme_support( 'editor-color-palette' );
add_action( 'after_setup_theme', 'wpdc_disable_gutenberg_custom_colour_palette' );

This will remove the predefined colours, while allowing users to select a custom colour.


The Gutenberg colour settings panel with all available options.


The Gutenberg colour settings panel with the colour palette disabled.

You might be wondering why this feature isn’t called disable-editor-colour-palette. This is because you are replacing the existing predefined palette included in WordPress Core with an empty palette.

By not passing a second argument to add_theme_support, the value for this feature is set as true. So when the Block Editor loads, it casts this value to an array. As there are no colours available, WordPress removes the colour palette from the interface.

How to Disable The Gutenberg Colour Settings Entirely?

In the two previous sections, we disabled specific colour features. To remove the entire colour settings panel, we combine these two code snippets into one:

function wpdc_disable_gutenberg_colour_settings() {
	add_theme_support( 'disable-custom-colors' );
	add_theme_support( 'editor-color-palette' );
add_action( 'after_setup_theme', 'wpdc_disable_gutenberg_colour_settings' );

As a result, the entire colour settings panel with be removed:

The Gutenberg paragraph block settings after having disabled the colour settings.

How To Define Custom Colour Palettes In A Theme?

To define your own colour palette, pass an array with the palette settings to the add_theme_support( 'editor-color-palette' ) call:

function wpdc_add_custom_gutenberg_color_palette() {
				'name'  => esc_html__( 'Brown', 'wpdc' ),
				'slug'  => 'brown',
				'color' => '#3a3335',
				'name'  => esc_html__( 'Orange', 'wpdc' ),
				'slug'  => 'orange',
				'color' => '#f0544f',
				'name'  => esc_html__( 'Light Green', 'wpdc' ),
				'slug'  => 'light-green',
				'color' => '#c6d8d3',

add_action( 'after_setup_theme', 'wpdc_add_custom_gutenberg_color_palette' );
  • The name value displays as a tooltip when the user hovers over the colour.
  • The Block Editor uses the hex value in color to style the block preview.
  • The slug is part of the CSS classes added to the block on the frontend.
The Gutenberg colour settings panel with a custom colour palette.

In addition, you need to define CSS classes in your theme’s stylesheet, both for the text and background colour variants:

.has-brown-background-color {
	background-color: #3a3335;

.has-brown-color {
	color: #3a3335;

.has-orange-background-color {
	background-color: #f0544f;

.has-orange-color {
	color: #f0544f;

.has-light-green-background-color {
	background-color: #c6d8d3;

.has-light-green-color {
color: #c6d8d3;


There you have it! All you need to know about custom colours in Gutenberg.

Go ahead and bookmark this article for future reference. If you liked this article, you might also enjoy these other articles talking about Gutenberg.

Block-Based Theme Development Course

Create beautiful themes for the Full-Site Editing mode.

The course is not available, yet. But if you subscribe now, you'll be among the first people to try it!