Adding gradients to your WordPress theme

Love ‘em or hate ‘em, gradients are here to stay. Especially now, as the WordPress block editor has a default mechanism to apply gradient styles throughout the editing experience.

Out of the box, I don’t find the default gradient application experience particularly meaningful, as these presets are an assortment of trendy gradient styles presets. But with some finesse, block editor gradients could be much more purposeful by using the editor’s color palette instead.

Let’s dive in and explore how it’s done.

Adding gradient presets

Adding gradient presets to the WordPress block editor is strikingly familiar to how themes provide a custom color palette. Using the add_theme_support( 'editor-gradient-presets' ) function, you may add as many gradients as you’d like.

Each gradient is provided as an array, with a name, gradient, and slug. The name is the label of the gradient, gradient is the actual CSS gradient value, and slug will become the class associated with the gradient. Here’s an example of registering a standalone gradient preset:

add_theme_support(
	'editor-gradient-presets',
	array(
		array(
			'name'     => __( 'Primary to Secondary', 'tabor' ),
			'gradient' => 'linear-gradient(135deg, rgba(255,0,0,.8) 0%, rgba(255,0,0,0) 100%)',
			'slug'     => 'primary-to-secondary',
		),
	)
);

Simple. Though I do think there’s an easy enough method to making the gradient presets much more meaningful to the person actually designing the website.

Using existing color palette colors in gradients

In an effort to make the gradient presets much more relevant, I explored how to map the colors provided by a theme’s add_theme_support( 'editor-color-palette' )  function, to the actual gradient presets. So here’s what I came up with:

1. Add an array of colors

To keep ourselves from repeating code (in this case, color values), we will want to build a single array of colors to pull those HEX values into both editor-color-palette and editor-gradient-presets.

$colors = array(
	'primary'   => '#db1c7d',
	'secondary' => '#a528f0',
	'tertiary'  => '#90cbff',
);

2. Register an editor color palette with the array

Now that we have our colors specified in the $colors array, we need to register those using the add_theme_support( 'editor-color-palette' ) function.

// Block Editor Palette.
$editor_color_palette = array(
	array(
		'name'  => __( 'Primary Color', 'tabor' ),
		'slug'  => 'primary',
		'color' => $colors[ 'primary' ],
	),
	array(
		'name'  => __( 'Secondary', 'tabor' ),
		'slug'  => 'secondary',
		'color' => $colors[ 'secondary' ],
	),
	array(
		'name'  => __( 'Tertiary', 'tabor' ),
		'slug'  => 'tertiary',
		'color' => $colors[ 'tertiary' ],
	),
);
add_theme_support( 'editor-color-palette', $editor_color_palette );

3. Convert HEX colors to RGB(A)

If you’re familiar with CSS gradients, they require the color values in RGB(A) format. That saying, we need to take our HEX values from the $colors array and provide a function to convert them to RGB(A).

/**
 * Convert a 3 or 6-digit hexadecimal color to an associative RGB array.
 *
 * @param string $color The color in hex format.
 * @param bool   $opacity Whether to return the RGB color is opaque.
 *
 * @return string
 */
function hex_to_rgb( $color, $opacity = false ) {

	if ( empty( $color ) ) {
		return false;
	}

	if ( '#' === $color[0] ) {
		$color = substr( $color, 1 );
	}

	if ( 6 === strlen( $color ) ) {
		$hex = array( $color[0] . $color[1], $color[2] . $color[3], $color[4] . $color[5] );
	} elseif ( 3 === strlen( $color ) ) {
		$hex = array( $color[0] . $color[0], $color[1] . $color[1], $color[2] . $color[2] );
	} else {
		$default                 = \Go\Core\get_default_color_scheme();
		$avaliable_color_schemes = get_available_color_schemes();
		if ( isset( $avaliable_color_schemes[ $default ] ) && isset( $avaliable_color_schemes[ $default ]['primary'] ) ) {
			$default = $avaliable_color_schemes[ $default ]['primary'];
		}
		return $default;
	}

	$rgb = array_map( 'hexdec', $hex );

	if ( $opacity ) {
		if ( abs( $opacity ) > 1 ) {
			$opacity = 1.0;
		}

		$output = 'rgba(' . implode( ',', $rgb ) . ',' . $opacity . ')';

	} else {

		$output = 'rgb(' . implode( ',', $rgb ) . ')';

	}

	return esc_attr( $output );

}

4. Register gradient presets

Finally, we’re ready to register our gradients using the add_theme_support( 'editor-gradient-presets' ) function. Referencing the $colors array and using the hex_to_rgb() function, we can now deploy our theme’s color palette to the gradient presets. In the following example, I’ve declared a few variants for gradient presets:

  • Primary to Secondary
  • Primary to Tertiary
  • Secondary to Tertiary
  • Tertiary to Primary
add_theme_support(
	'editor-gradient-presets',
	array(
		array(
			'name'     => __( 'Primary to Secondary', 'tabor' ),
			'gradient' => 'linear-gradient(135deg, ' . esc_attr( hex_to_rgb( $colors[ 'primary' ] ) ) . ' 0%, ' . hex_to_rgb( $colors[ 'secondary' ] ) . ' 100%)',
			'slug'     => 'primary-to-secondary',
		),
		array(
			'name'     => __( 'Primary to Tertiary', 'tabor' ),
			'gradient' => 'linear-gradient(135deg, ' . esc_attr( hex_to_rgb( $colors[ 'primary' ] ) ) . ' 0%, ' . hex_to_rgb( $colors[ 'tertiary' ] ) . ' 100%)',
			'slug'     => 'primary-to-tertiary',
		),
		array(
			'name'     => __( 'Secondary to Tertiary', 'tabor' ),
			'gradient' => 'linear-gradient(135deg, ' . esc_attr( hex_to_rgb( $colors[ 'secondary' ] ) ) . ' 0%, ' . hex_to_rgb( $colors[ 'tertiary' ] ) . ' 100%)',
			'slug'     => 'secondary-to-tertiary',
		),
		array(
			'name'     => __( 'Tertiary to Primary', 'tabor' ),
			'gradient' => 'linear-gradient(135deg, ' . esc_attr( hex_to_rgb( $colors[ 'tertiary' ] ) ) . ' 0%, ' . hex_to_rgb( $colors[ 'primary' ] ) . ' 100%)',
			'slug'     => 'tertiary-to-primary',
		),
	)
);

A better gradient experience

After applying the steps above, the WordPress themes’s color palette and gradient presets will match each other — affording a better experience applying gradients throughout the editor. Instead of those flashy gradient styles, the end user will have a selection of relevant — on brand — gradients to apply.

If you’ll find it helpful, you can check out the full source code here, with all the steps combined. As a side-note, allowing users to choose the colors that display within the block editor is an even better user-experience.

I do recommend looking into how to leverage the Customizer to allow users to pick their own colors — which we’ve implemented in the Go WordPress theme.

So what do you think?

Will you be updating your WordPress themes to better support gradient presets in Gutenberg?

Responses

  1. Sébastien Dumont Avatar

    Is it only in themes that you can add gradients or can you apply the same custom gradients to a custom block without adding support?

    1. Rich Tabor Avatar

      I believe you can override the theme’s gradients – if it provides one. Good question!

  2. Heather New Avatar

    This is a good solution, thanks for sharing your exploration Rich!

  3. Ian Markind Avatar

    Very useful, thank you!

Leave a Reply

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

%d