How to add gradient text to WordPress blocks

Here’s a simple CSS trick to add support for gradient text in WordPress that can be customized using only core block features. This example uses the Heading block with the background color setting, but it can be changed to your needs.

The first step is to add the required CSS to your site, this can be placed in a child theme’s style.css file or within a custom plugin. The code snippet below will add gradient support to the Heading block with a H1 level, but you can change the selectors below to your liking if you wish to use gradients with other blocks:

Once the above code snippet has been added to your site, you will be able to select gradient colors using the Background Color setting when editing the heading block as demonstrated in the screen recording below:

Please Note: Since this method uses the background color setting to mask the text, it can no longer be used as the actual background color behind the text. Instead, simply place the heading block inside a Group block and then adjust the background of the Group container block.

Breaking down the CSS code snippet

The code snippet used in this example uses some simple CSS tricks to enable text gradients. Here’s some further details of how it works, and how you can change it to suit your project:


The class selectors target any H1 heading element with a class containing “-gradient-background”. This handles theme and user preset gradients that use named classes and custom properties to apply the value.


This selector handles custom gradients not included in the preset list. This allows users to select any color from the editor. It looks for any element that contains “-gradient” in the inline style attribute.

-webkit-background-clip: text !important

Masks the text with the background image/color. This is the crucial part of the CSS that makes this work.

color: transparent

Reset the current text color to transparent to allow the mask to work.

padding: 0

By default, WordPress adds some padding to heading and paragraph blocks if a background color set. This removes the default padding, but if a custom padding value is set in the editor it will override this reset.

Better approaches to adding text gradients

While this CSS trick works well, there are some other approaches that provide a nicer and less confusing user experience. In my opinion, this functionality is better served by text formats instead of block settings.

Text Format

Ideally, WordPress would add gradient support to the Highlight rich text format. The Highlight format can be accessed from the Block Toolbar for any block which uses rich text and supports text highlighting. Below is a screenshot of the highlight format which would be perfect for text gradients (I’m sure support will be added to core soon):

Block Style

Rather than targeting every element with gradient set, you could instead register a new block style called Gradient Text. With this approach, only blocks with this block style active will convert the background color to the text color.

Custom Class

Another option is to create a custom CSS class, for example .has-gradient-text. Custom classes can be added from the Advanced section of the block settings.

Please note that if using the code snippet above you will need to change the selectors from the existing to the custom class name.

Other approaches

The CSS trick in this article is only intended to be used as an example starting point and there are most likely better ways to achieve this. By now, there’s probably a number of free block toolkit plugins available that add support for text gradients without requiring custom CSS.

The Blockify theme comes with a Gradient Text format for all blocks that use the Rich Text field. This includes buttons, lists, links, headings, paragraphs and more. If/when support for gradients is added to WordPress core, this feature will be deprecated and we will switch to the native feature instead.

Below is a preview of how to apply a custom gradient to a selection of text in the Blockify theme:

More text gradient tricks with CSS

Here’s a few more cool things that you may discover while working with text gradients in WordPress. These are all possible with the above code snippet (with the CSS selectors adjusted to all blocks).

Gradient Emojis

One unexpected thing that I have found is that gradients also work for emojis when applied as a text format. This also works with the highlight text format, although it currently only supports solid colors:


Gradient Button Text

Gradient text can also be applied to the Button block since it uses the Rich Text field. Please note that the button line-height may need to be increased to prevent any cropping of the masked text:

Gradient Border

While not gradient text, gradient borders are sometimes needed when working with gradient text. Here is one way to achieve gradient borders in WordPress using only core blocks and no CSS. It uses a group block with a gradient background color and 2px padding, then an inner block with a solid background matching the body background color to appear as a transparent background.:

Group block gradient border trick!

Gradient Box Shadow

Since CSS doesn’t support gradient shadows, it usually requires a complex workaround to enable this functionality.

One way is to apply a CSS blur to an absolute positioned element with a gradient background set. This can create performance issues when overused, so I recommend using it lightly when there are no better options. Here’s a live example, you can use your browsers code inspector to see how it works:

Gradient box shadow

Gradient text support in WordPress core

I would like to see support for text gradients added to WordPress core so that themes and plugins don’t have to create and maintain their own settings. I’m sure this will be added in the near future, given the speed of improvement with the block editor. It’s quickly becoming a powerful design tool for theme developers.

If you have any questions or suggestions please feel free to leave a comment below, or alternatively send us a message from our support form, we’re happy to answer any block related questions. Thank you for reading and I hope you find it helpful.

Leave a Reply

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