When Block Styles Are Not Enough: Extending Blocks in Themes

[justintadlock]

Tutorial proposal:

One of the oft-repeated issues with WordPress' block styles system is that users can only add one style to a block at a time. More on this Gutenberg ticket: WordPress/gutenberg#14598

There are pros and cons to this system:

• Pro: It keeps highly distinctive styles from clashing.
• Con: You can't mix and match simpler or smaller design pieces that wouldn't clash.

There has to be a middle ground...

How to combine block styles?

That is the question that has frustrated many developers. For example, suppose you had a "Large Text" style and a separate "Gradient Outline" style for the block. Do you create a third style named "Large Text with Gradient Outline"? That is what some devs have resorted to, but it is a slippery slope with each new style you add. And, you would never do this in a solid design system.

At the end of the day, a block style is nothing more than a simple class that uses a standard .is-style-{$slug} naming scheme. The reason this is great for themes is that it doesn't negatively impact user content if/when users switch themes.

And this is (relatively) simple to recreate.

On the most low-effort DX end of the scale, you just have users input custom classes into the "Additional CSS Class(es)" box and call it a day. But, that makes for a poor UX.

On the other end of the spectrum, you build custom controls and let the user interact with them through the interface. Unlike custom blocks or plugins that add custom attributes, this system would use CSS classes under the hood. That means it also plays nicely with the WordPress theme review guidelines.

I've created several solutions in the past couple of weeks for testing this system. It works really, really well.

For example, here's a "Gradient Outline" picker that I put together:

Teaching theme authors block editor JavaScript

There are two things at play:

1. Theme authors must first learn how to set up the @wordpress/scripts package and integrate it into a theme. AFAIK, there is no documentation aimed directly at theme dev, but it definitely works.
2. Introduce theme authors to concepts that would typically fall under "block" development.

This is potentially a two-part series because both of the topics could be relatively beefy on their own.

[justintadlock]

Sharing some other custom alternatives to block styles:

Text shadows

This one is probably the simplest, so it'd make for a good introduction to the concept in the post:

List markers/bullets

This one is almost as simple as the text-shadow, but it has an extra hurdle to jump when dealing with <ul> vs. <ol>:

Color variations (color groups) for style entire sections

This is probably too complex for an introductory tutorial because it would need to discuss color design systems in detail:

[marybaum]

You've got my vote! I'm dealing with all these and more on a site I'm building — well, actually, I'm doing without.

[justintadlock]

I was trying to think of a use case that would show off what you could do while also being a bit fun. Since I had no electricity for the day, a full laptop battery charge, and nothing but my imagination to keep me company, I present to you an emoji-fied Separator block. Right now, this just uses the regular block styles system, but you can see how easily that gets out of hand. This should be also be a simple enough example to keep this tutorial within a reasonable length.

The big things would be:

• Creating a custom control for the icon/emoji selection via a block filter.
• Pairing each emoji with a core background-color/gradient and setting this dynamically (can probably pair these with theme-defined gradients too). Haven't tried this yet, so I'm hoping this isn't any tougher than using setAttributes from within the filter.
• Removing the block style class (if the user adds one since this wouldn't pair well with other styles). I'm actually not sure of the best way to do this just yet.

separator-icon-styles.mp4

Backup of SCSS for safekeeping:

// Icon styles.
hr.wp-block-separator[class*=is-style-icon] {
	display: flex;
	justify-content: center;
	border: none;
	text-align: center;

	// Some characters get cut off. This ensures they are visible.
	overflow: visible;

	// Use `!important` to overrule core's use of the `background` shorthand
	// instead of the targeted property itself.
	background-color: transparent !important;
	background-repeat: repeat-x !important;
	background-position: 0% 50% !important;
	background-size: 100% 2px !important;

	// Don't use `!important` for the background image, which allows
	// background gradients to work.
	background-image: var( --hr-bg, linear-gradient( 90deg, currentColor, currentColor ) );

	// If there's a background color, use our custom gradient which uses the
	// current color.
	&:where( [class*=-background-color] ) {
		background-image: linear-gradient( 90deg, currentColor, currentColor );
	}

	&::before {
		content: var( --hr-icon, "\2766" ); // floral heart default.
		padding: 0 0.25em;
		font-size: var( --wp--preset--font-size--xl );
		line-height: 1;
		background-color: var( --color-base, var( --wp--preset--color--base ) );
	}
}

.is-style-icon-♫ { --hr-icon: "♫"; } // beamed eighth notes
.is-style-icon-★ { --hr-icon: "★"; } // black star
.is-style-icon-❦ { --hr-icon: "❦"; } // floral heart
.is-style-icon-☘ { --hr-icon: "☘"; } // shamrock
.is-style-icon-✻ { --hr-icon: "✻"; } // teardrop spoked asterisk

// We can set these backgrounds dynamically if moving to a custom control and 
// outside of the block styles system.
.is-style-icon-☀️  { --hr-icon: "☀️";  --hr-bg: var( --wp--preset--gradient--true-sunset ); }
.is-style-icon-🪶 { --hr-icon: "🪶";  --hr-bg: var( --wp--preset--gradient--shy-rainbow ); }
.is-style-icon-🍃 { --hr-icon: "🍃"; --hr-bg: var( --wp--preset--gradient--emerald ); }
.is-style-icon-✏️  { --hr-icon: "✏️"; --hr-bg: var( --wp--preset--gradient--mohave ); }
.is-style-icon-🌻 { --hr-icon: "🌻"; --hr-bg: var( --wp--preset--gradient--true-sunset ); }
.is-style-icon-⛱️ { --hr-icon: "⛱️"; --hr-bg: var( --wp--preset--gradient--powerpuff ); }

[justintadlock]

I ended up turning this into a custom control:

separator-icon-styles-002.mp4

[hanneslsm]

Thank you, this looks promising!
I also like the custom controls.
The only issue I have is that those are in the toolbar, which makes the UI feels messy ("what can I find where again?"). Can these also been shown in the sidebar? Maybe with preselected emojis, but if possible also via an input field for custom ones?

For simple use cases, I recently ran into that I wanted to add:

1. Transform on hover (e.g. transform: scale(1.1)) on groups)
2. Add slight shadow on hover
3. Add slight fade-in animation on scroll (also with js, not only css)

Use case 2:

1. Style A: image with a border and outline ("picture frame"), style B: Polaroid
2. Caption below the images, either in sans serif or written on the Polaroid with a handwriting font
3. Optionally tilting the images a little bit
4. Adding predefined shadows

Use case 3:
Adding colored shadows, depending on the background color (I imagined a simple toggle that says: "Shadow: Use Background Color")

[justintadlock]

The only issue I have is that those are in the toolbar, which makes the UI feels messy ("what can I find where again?"). Can these also been shown in the sidebar? Maybe with preselected emojis, but if possible also via an input field for custom ones?

All of that is possible. Moving from the toolbar to the inspector controls sidebar shouldn't be a big change. I'll do a little work with that to see what I come up with before diving into the tutorial.

It's very possible for an input field for custom emoji, but I probably won't show that in the guide. That would require adding a custom attribute, which I don't think would be allowed in the WordPress theme directory. But, it'd be very doable for client/personal projects.

The primary goal of this tutorial is going to be about teaching some foundational concepts more than providing a specific solution for any specific problem. Ultimately, it's about giving folks the tools to extend the editor however they want.

---

Your other use cases look great too!

I've got a little work finished on polaroid-style images myself, but I want to create some custom "tilt" controls using the concepts laid out in this post. I'll be happy to share that whenever I get around to it.

[mrwweb]

A huge +1 for this! I've written a somewhat similar post on my blog which I'm happy to share as inspiration/reference.

I'm most excited because of this:

Theme authors must first learn how to set up the @wordpress/scripts package and integrate it into a theme. AFAIK, there is no documentation aimed directly at theme dev, but it definitely works.

I believe you're right this doesn't exist and I haven't been able to find any information about this when trying to figure it out for myself. I've got a current setup, but I'll be very interested to see how yours compares. Either way, this is super important information and should probably morph into a Handbook page eventually.

[acketon]

Love this! I'd like to see this documentation as it's a use case we would likely make use of in our managed network. We have plugins with custom blocks in them, but inevitably will have custom themes that are developed that need to modify those blocks which would be preferable to building a similar block from scratch for that client. Figuring out a maintainable and efficient way to extend blocks in a theme in some ways is really important. I'd be especially interested in tips for ensuring those changes made in the theme can be as safe as possible during WP upgrades to avoid breaking, etc.

[bph]

The topic has been approved. The discussion is now locked,
Please continue the conversation on the issue

• When Block Styles Are Not Enough: Extending Blocks in Themes #144