Theme.json Color Options - Full Site Editing

In this lesson, you will learn how to use all the theme.json color options, including:

• Site-wide and block specific color palettes
• Enable or disable custom colors (color picker)
• Enable or disable gradients, duotone, link- and border colors
• Adding default colors to blocks

At the end of the lesson, you will also find answers to frequently asked questions.

All code examples in this lesson assumes that you are using theme.json version 2 or 3. Remember that you must include the version in your .json file.

Prerequisites: Global Styles & theme.json.

Written by:

Carolina Nymark

Level: Beginner, Developer

Estimated reading time: 13 minutes

Last updated

June 19, 2024

Table of contents

• Introduction
  • What color options can you change with theme.json?
  • What colors can you not change with theme.json?
  • What color values can you use in theme.json?
  • JSON structure
• Color palettes
  • The default color palette
  • How to hide the default color palette
  • How to add a new color palette
  • How to add a color palette for a block
  • How to add multiple color palettes
• How to enable border color and link color options in theme.json
• How to disable color options
• Duotone
  • Which WordPress blocks support duotone?
  • Default duotones
  • How to add duotone colors
  • How to disable duotone
  • How to set a default duotone using theme.json
• Gradients
  • Which WordPress blocks support gradient backgrounds?
  • Default gradients
  • How to hide the default gradients
  • How to add gradients to the block editor
  • How to disable gradients
• Applying colors with theme.json
  • Text color
  • Background color
  • How to add a default gradient background to a block
  • Applying colors using theme.json elements
  • Border color
• Frequently asked questions

Introduction

What color options can you change with theme.json?

The WordPress block editor has many different types of color options:

• Background color: Solid and gradient
• Text color
• Link text color, link hover color
• Border color
• Inline text color (Highlight)
• Duotone
• Cover block overlay

If you want to learn about the shadow options, I have written about them in a separate lesson.

With theme.json, you can:

• Decide which colors, gradients, and duotones the user can choose from
• Decide if the user should be able to select custom colors using the color picker
• Disable and enable link color, border colors, gradients, and duotones
• Use different color options per block
• Apply default colors to many blocks

What colors can you not change with theme.json?

You may run into problems when you apply colors to complex blocks with multiple HTML elements. For example, in a block like the latest posts block you can not add different colors for the post date and post author (not without custom CSS).

What color values can you use in theme.json?

Except for duotones, you can use any valid CSS color values to add or apply colors. Such as hex, rgb, rgba, color names like blue or red, keywords like transparent and currentColor, hsl, and hsla. You can also use a CSS custom property. Duotone only works with hex and RGB color values.

JSON structure

All three color options: the palette, duotone, and gradients use the same JSON structure with key and value pairs:

• slug: The unique identifier. Also used in the CSS custom property.
• name: The visible name of the color in the editor.
• color/gradient/duotone: The CSS color value.

Color palettes

There are three types of color palettes: The default palette added by WordPress, a palette that can be added and customized by the user, and the theme palettes.

The default color palette

WordPress registers colors in its default color palette with CSS custom properties that are available for all themes. This is so the default colors don’t break if the user switches themes, and to make it easier for us to use patterns from the pattern directory.

The palette is persistent: even if you hide it or add a new color palette, the CSS custom properties for these colors remain.

–wp–preset–color–black: #000000;

–wp–preset–color–cyan-bluish-gray: #abb8c3;

–wp–preset–color–white: #ffffff;

–wp–preset–color–pale-pink: #f78da7;

–wp–preset–color–vivid-red: #cf2e2e;

–wp–preset–color–luminous-vivid-orange: #ff6900;

–wp–preset–color–luminous-vivid-amber: #fcb900;

–wp–preset–color–light-green-cyan: #7bdcb5;

–wp–preset–color–vivid-green-cyan: #00d084;

–wp–preset–color–pale-cyan-blue: #8ed1fc;

–wp–preset–color–vivid-cyan-blue: #0693e3;

–wp–preset–color–vivid-purple: #9b51e0;

How to hide the default color palette

You can hide the default palette in the editor by setting it to false in settings.color:

Copy"settings": { "color": { "defaultPalette": false } }

Or, hide it for a single block type:

Copy"settings": { "blocks": { "core/paragraph": { "color": { "defaultPalette": false } } } }

How to add a new color palette

You can create a new color palette inside settings.color in theme.json:

Copysettings.color.palette

You list the palette colors inside an array, encasing them with curly brackets and separating them with a comma:

Copy"settings": { "color": { "palette": [ { "slug": "primary", "color": "#7c027c", "name": "Purple" }, { "slug": "secondary", "color": "#420142", "name": "Dark purple" } ] } }

WordPress parses the JSON and creates a CSS custom property for each color, and adds them to the <body> element:

Copybody { --wp--preset--color--primary: #7c027c; --wp--preset--color--secondary: #420142; }

These properties are available in addition to the custom properties for the default palette.

How to add a color palette for a block

You can create separate color palettes for blocks under the blocks section inside the settings section:

Copysettings.blocks.blockname.color.palette

Example:

Copy"settings": { "blocks": { "core/paragraph": { "color": { "palette": [ { "slug": "primary", "color": "#7c027c", "name": "Purple" }, { "slug": "secondary", "color": "#420142", "name": "Dark purple" } ] } } } }

The block-specific CSS custom properties are not added to the <body>, but to the block selector:

Copyp { --wp--preset--color--primary: #7c027c; --wp--preset--color--secondary: #420142; }

It is not possible to add separate palettes for block variations, such as having one palette for the row and another for the stack (Row and stack are variations of the group block).

How to add multiple color palettes

From WordPress 6.6, with a planned release in July 2024, themes can add multiple palettes that the user can choose from in the Color panel in the Styles sidebar in the Site Editor. Once a user has selected one of these color palettes, the available colors are updated across the site.The palette can also be reset.

• The default theme palette is the one you include in theme.json.
• The optional theme palettes are global style variations that only update the color palette.

These “palette variations” use the same format as theme.json and are placed inside the theme’s styles folder.

How to enable border color and link color options in theme.json

• List of blocks that support border color
• Blocks that support link color

Even if a block does not have a link color control, you can still set default colors with theme.json, but the user can’t change the colors.

Copy"settings": { "border": { "color": true }, "color": { "link": true } }

You can also enable this site-wide, but disable it for specific blocks.Switch the true and false values to disable link color site-wide and enable them for the single block. The border color option works the same way.

Copy"settings": { "color": { "link": true }, "blocks": { "core/list": { "color": { "link": false } } } }

How to disable color options

There are a few different ways to disable color palettes and color options.

You can remove the color palette for all blocks by leaving the array of colors empty:

Copy"settings": { "color": { "palette": [] } }

Or you can remove it for a single block:

Copy"settings": { "blocks": { "core/paragraph": { "color": { "palette": [] } } } }

You can disable background, text, and link colors separately:

Copy"settings": { "color": { "background": false, "link": false, "text": false } }

The link color is disabled (false) by default but added here as an example. There is no way to disable the link hover color option using theme.json, only all of the link color options.

Here is an example of how to disable the background color for a single block type.With this example, the palette for the text color is still available unless it has been disabled globally.

Copy"settings": { "blocks": { "core/paragraph": { "color": { "background": false } } } }

How to disable the custom color picker

You can disable custom colors (the color picker) for all blocks by setting color.custom to false inside the settings section:

Copy"settings": { "color": { "custom": false } }

Here is how you would disable custom colors for a single block:

Copy"settings": { "blocks": { "core/paragraph": { "color": { "custom": false } } } }

You can use the following code to disable the color picker for all blocks except the paragraph:

Copy"settings": { "color": { "custom": false }, "blocks": { "core/paragraph": { "color": { "custom": true } } } }

Duotone

Duotone is a filter where you pair two colors to create effects for videos and images.Duotones use a CSS custom property in the following format:

Copy--wp--preset--duotone--slug

Read more about the introduction of duotones in WordPress:

WordPress.org: Coloring Your Images With Duotone Filters

WP Tavern: Duotone Filters: WordPress 5.8 Puts a Powerful Image-Editing Tool Into Users’ Hands

Which WordPress blocks support duotone?

The cover block, image, featured image, avatar and site logo supports duotone (June 2024).

Default duotones

Dark grayscale

Grayscale

Purple and yellow

Blue and red

Midnight (Black and blue)

Magenta and yellow

Purple and green

Blue and orange

How to add duotone colors

You can add new duotones inside the settings section of theme.json:

Copysettings.color.duotone

In comparison to the color palette which takes one color value, the duotone takes an array with two color values. So the first color is the shadow, and the second color is the highlight. Separate the values with a comma.

Important: Duotone only works with the hex and rgb color formats:

Copy"colors": [ "#cc1871", "#f9449e" ]

If you add more than two colors, the effect will only use the first two colors.

Example of how to add a new duotone for all blocks that support the feature (site-wide):

Copy"settings": { "color": { "duotone": [ { "colors": [ "#cc1871", "#f9449e" ], "slug": "pink-and-light-pink", "name": "Pink and light pink" } ] } }

And for a single block:

Copy"settings": { "blocks": { "core/cover": { "color": { "duotone": [ { "colors": [ "#cc1871", "rgb(255,255,255)" ], "slug": "pink-and-white", "name": "Pink and white" } ] } } } }

How to disable duotone

You need to add an empty duotone color array and set default and custom duotones to false to completely disable duotone:

• "duotone": [] disables the palette
• "customDuotone": false disables the color picker
• "defaultDuotone": false disables the default colors

Copy"settings": { "color": { "duotone": [], "customDuotone": false, "defaultDuotone": false } }

How to disable duotone for a single block:

Copy"settings": { "blocks": { "core/cover": { "color": { "duotone": [], "customDuotone": false, "defaultDuotone": false } } } }

To only disable custom duotones (the color picker), you can set color.customDuotone to false:

Copy"settings": { "color": { "customDuotone": false } }

How to disable the custom duotone color picker for single blocks:

Copy"settings": { "blocks": { "core/image": { "color": { "customDuotone": false } } } }

How to set a default duotone using theme.json

You can set a default duotone for supported blocks. In this example I am using one of the default duotones with the image block. Note the use of filter instead of color:

Copy"styles": { "blocks": { "core/image": { "filter": { "duotone": "var(--wp--preset--duotone--magenta-yellow)" } } } }

Gradients

Which WordPress blocks support gradient backgrounds?

Please see the list of blocks that support gradients in the block reference.

Default gradients

The default gradients are persistent as the CSS custom properties are output even if you disable gradients in your theme. This prevents the colors from breaking if the user has used the gradients and then changes themes.

–wp–preset–gradient–vivid-cyan-blue-to-vivid-purple:linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%);

–wp–preset–gradient–light-green-cyan-to-vivid-green-cyan:linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%);

–wp–preset–gradient–luminous-vivid-amber-to-luminous-vivid-orange:linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%);

–wp–preset–gradient–luminous-vivid-orange-to-vivid-red:linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%);

–wp–preset–gradient–very-light-gray-to-cyan-bluish-gray:linear-gradient(135deg,rgb(238,238,238) 0%,rgb(169,184,195) 100%);

–wp–preset–gradient–cool-to-warm-spectrum:linear-gradient(135deg,rgb(74,234,220) 0%,rgb(151,120,209) 20%,rgb(207,42,186) 40%,rgb(238,44,130) 60%,rgb(251,105,98) 80%,rgb(254,248,76) 100%);

–wp–preset–gradient–blush-light-purple:linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%);

–wp–preset–gradient–blush-bordeaux: linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%);

–wp–preset–gradient–luminous-dusk: linear-gradient(135deg,rgb(255,203,112) 0%,rgb(199,81,192) 50%,rgb(65,88,208) 100%);

–wp–preset–gradient–pale-ocean: linear-gradient(135deg,rgb(255,245,203) 0%,rgb(182,227,212) 50%,rgb(51,167,181) 100%);

–wp–preset–gradient–electric-grass:linear-gradient(135deg,rgb(202,248,128) 0%,rgb(113,206,126) 100%);

–wp–preset–gradient–midnight:linear-gradient(135deg,rgb(2,3,129) 0%,rgb(40,116,252) 100%);

How to hide the default gradients

Copy"settings": { "color": { defaultGradients": false } }

How to add gradients to the block editor

You add gradients under the settings section of theme.json:

Copysettings.color.gradients

Use any valid CSS gradient: linear, radial, conic, or repeating, with any number of colors and opacity. Example:

Copy"settings": { "color": { "gradients": [ { "slug": "pink-to-pale-purple", "gradient": "linear-gradient(to bottom right,rgba(255,30,142) 49.9%,rgb(229,6,229, 0.36) 50%)", "name": "Diagonal pink to pale purple" } ] } }

You can also experiment with different shapes and hard stops:

CSS output:

Copybody { --wp--preset--gradient--pink-to-pale-purple: linear-gradient(to bottom right,rgba(255,30,142) 49.9%,rgb(229,6,229, 0.36) 50%); }

How to add gradients for different WordPress blocks:

Copy"settings": { "blocks": { "core/group": { "color": { "gradients": [ { "slug": "pink-to-pale-purple", "gradient": "linear-gradient(to bottom right,rgba(255,30,142) 49.9%,rgb(229,6,229, 0.36) 50%)", "name": "Diagonal pink to pale purple" } ] } }, "core/search": { "color": { "gradients": [ { "slug": "white-to-grey", "gradient": "linear-gradient(90deg, rgb(255,255,255) 0%, rgb(203,203,203) 49%, rgb(255,255,255) 98%)", "name": "White to grey" } ] } } } }

CSS output:

Copy.wp-block-group { --wp--preset--gradient--pink-to-pale-purple: linear-gradient(to bottom right,rgba(255,30,142) 49.9%,rgb(229,6,229, 0.36) 50%); } .wp-block-search { --wp--preset--gradient--white-to-grey: linear-gradient(90deg, rgb(255,255,255) 0%, rgb(203,203,203) 49%, rgb(255,255,255) 98%); }

How to disable gradients

You need to add an empty gradients array and set default and custom gradients to false to disable gradients site-wide:

Copy"settings": { "color": { "gradients": [], "customGradient": false, "defaultGradients": false } }

Next is an example of how to disable gradients for a single block:

Copy"settings": { "blocks": { "core/group": { "color": { "gradients": [], "customGradient": false, "defaultGradients": false } } } }

Applying colors with theme.json

In the first part of this lesson, we went through how to add color options to the editor.Next, I will show you some practical examples of applying colors to blocks in the styles section of theme.json.

One thing to keep in mind is that you are not limited to using presets that you created in the settings section. You can use any valid CSS color value.

Text color

Colors on the root level of the styles section in theme.json are applied to the HTML body.

Copystyles.color.text Copy"styles": { "color": { "text": "var(--wp--preset--color--black)" } }

CSS Output:

Copybody { color: var(--wp--preset--color--black); }

The next example shows how to add a default text color to a single block:

Copy"styles": { "blocks": { "core/verse": { "color": { "text": "var(--wp--preset--color--black)" } } } }

And the resulting CSS output for the verse block is:

Copy.wp-block-verse { color: var(--wp--preset--color--black); }

Background color

You add the body background color the same way you add the text color:

Copystyles.color.background Copy"styles": { "color": { "background": "var(--wp--preset--color--black)" } }

CSS output:

Copybody { background-color: var(--wp--preset--color--black); }

The code for adding a background for a single block is equally straightforward:

Copy"styles": { "blocks": { "core/search": { "color": { "background": "var(--wp--preset--color--black)" } } } }

CSS output:

Copy.wp-block-search { background-color: var(--wp--preset--color--black); }

How to add a default gradient background to a block

You can add default gradients to supported blocks using styles.color.gradient.

Copy"styles": { "blocks": { "core/heading": { "color": { "gradient": "var(--wp--preset--gradient--cool-to-warm-spectrum)" } } } }

CSS output:

Copyh1, h2, h3, h4, h5, h6 { background: var(--wp--preset--gradient--cool-to-warm-spectrum); }

Applying colors using theme.json elements

You use the elements object to apply styles to links, headings, buttons and more.Please read this lesson to learn more about elements.Styling site wide links:

Copy"styles": { "elements": { "link": { "color": { "text": "var(--wp--preset--color--secondary)" } } } }

CSS output:

Copya { color: var(--wp--preset--color--secondary); }

Use the heading levels H1 to H6 to add default colors to headings:

Copy"styles": { "elements": { "h1": { "color": { "text": "var(--wp--preset--color--secondary)" } } } }

CSS output:

Copyh1 { color: var(--wp--preset--color--secondary); }

Styling buttons:

Copy"styles": { "elements": { "button": { "color": { "text": "var(--wp--preset--color--secondary)", "background": "var(--wp--preset--color--primary)" }, "border": { "color": "var(--wp--preset--color--pale-pink)" } } } }

You can also add background colors to links:

Copy"styles": { "elements": { "link": { "color": { "text": "white", "background": "#222222" } } } }

One use case for the link background color is to style the pagination. Remember that when you apply styling to blocks, the styles first need to be placed inside the blocks object:

Copystyles.blocks.blockname.elements.link.color.text styles.blocks.blockname.elements.link.color.background Copy"styles": { "blocks": { "core/query-pagination": { "elements": { "link": { "color": { "text": "#fff", "background": "#222" } } } } } }

Another use case for adding a background color to links is to highlight post titles and read more links, like in this example that the WordPress designer and developer Tammie Lister used on one of their websites:

Styling the post excerpt read more text can seem tricky. -First the block needs to have the link option enabled and a custom read more text, otherwise, there is no link element to style.

In this example, I have included padding to make the background color more visible:

Copy"styles": { "blocks": { "core/post-excerpt": { "elements": { "link": { "color": { "background": "var(--wp--preset--color--pale-cyan-blue)" }, "spacing": { "padding": { "top": "0.6rem", "right": "1rem", "bottom": "0.6rem", "left": "1rem" } } } } } } }

Border color

Which WordPress blocks support borders?

All blocks can have a default border added in theme.json. The following blocks have support for border color, style, width, and radius: Avatar, code, column, columns, comments title, group, image, post featured image, pullquote, read more, and search.

The button block and image block have controls for border radius. The table block and column has controls for style, width, and color, but not radius.

For the border controls to be visible in the editor, you need to enable the feature.

Border color examples

When you add a border color you also need to add a border style for the border to be visible:

Copy"styles": { "border": { "style": "solid", "color": "var(--wp--preset--color--pale-pink)" } }

One use case for adding borders to the body element could be for boxed layouts.

Button block and pull quote code examples:

Copy"settings": { "border": { "customColor": true, "customRadius": true, "customStyle": true, "customWidth": true } }, "styles": { "blocks": { "core/button": { "border": { "style": "solid", "color": "var(--wp--preset--color--pale-pink)" } }, "core/pullquote":{ "border": { "width": "4px", "radius": "10px", "style": "dotted", "color": "var(--wp--preset--color--cyan-bluish-gray)" } } } }

Frequently asked questions

How should I name the colors?

It is recommended to use base and contrast followed by primary, secondary, tertiary, and so on as the color slug and name.Example:Your background color: “slug”: “base”, “color”: “#ffffff”, “name”: “Base”Your foreground color: “slug”: “contrast”, “color”: “#111111”, “name”: “Contrast”If more themes use this naming convention, it will be easier for the user to change themes and keep the color contrast and readability of their existing content.You can follow the discussion about best practices and the naming convention in this overview issue on GitHub: Default Colors, Theme Colors, and Custom Colors.

Can I use separate palettes for background and text color?

This is not possible with theme.json. There was a GitHub issue with a proposal to add contextual palettes, but the issue was closed with the comment that there are no plans to implement this.

Previous: Exercise: Creating theme.json Next: Theme.json typography options: Font family and size