selecting shadows or highlights beneath the preview bar will present theme colors

Customizing images with WordPress duotone filters

3 min read
Courtney Robertson

In version 5.8, WordPress duotone filters launched. Duotone filters allow content creators to add unique appearances to their photos without editing the photo files.

Here you will want to consider how clients can make use of these colors. What options will you want readily available for clients to select when adding an image? Read on to learn how to use and configure WordPress duotone filters.

Hub Signup

What is duotone?

Duotone refers to using two contrasting colors, or a double tone. Similar to using grayscale on images, using a duotone effect is to use two colors for darks and lights on an image.

WordPress duotone filters enable you to select unique colors for the shadows and highlights of a photo. You can use a preset, colors from your theme’s palette, or a custom color of your choice.

Original images are safe with the duotone filter. The duotone effect works using SVG filters and the CSS filter property, but will not show up in RSS feeds or places that directly use the image URL.

How to use WordPress duotone filters

Creating artistic effects in your images is possible within the block editor without overwriting your image file. Let's look at how to use duotone images.

1. Insert an image into your post

Adding an image that has high contrast rates will make duotone images really stand out. In the image block toolbar, you can select the duotone button.

2. Select from the duotone filter options

From here, you can select from default options.

select the duotone option from the image block toolbar

3. Customize using the color picker

Clicking the circles in the preview bar will allow you to select any color you'd like, or enter in a color value manually.

WordPress duotone filter preview color picker

Selecting either the Shadows or Highlights option will reveal colors that are part of your theme's color palette. This is a great way to follow the predefined design assets on your site.

selecting shadows or highlights beneath the preview bar will present theme colors

Note: the clear button will remove all effects.

Creating WordPress duotone theme options

Theme developers and those building websites for clients may want a bit more control over what duotone options are available to clients. For that, we'll need to look at Theme.json.

Theme.json is a new method to manage all the options available to those who use your theme (or child theme). With it, you can define what choices users have when styling their websites.

To see an example of specific theme.json code, check the example from the WordPress Developer Documentation:

    "version": 1,
    "settings": {
        "color": {
            "duotone": [
                    "colors": [ "#000", "#FFF" ],
                    "slug": "black-and-white",
                    "name": "Black and White"

See also the documentation for Supports Color in the Block Editor Handbook to style options in specific blocks.

For a more extensive dive into developing duotone configuration options, check out this tutorial from FullSiteEditing. Here you can find a way to add support for all blocks on your site, or isolate the duotone options to specific block types, or even disable duotone options.

You can get a look at how WordPress duotone filters are applied to specific block types to appear in Anne's tutorial. Anne is a developer relations manager, sponsored by Automattic, to lead the WordPress Full Site Editing Outreach program.