Register a custom block style in Gutenberg with simple PHP and CSS- no JavaScript or build process required.

👉 Full Code https://github.com/bacoords/example-block-style
👉 Full Tutorial https://www.briancoords.com/custom-lists-in-wordpress-with-register-block-style/
👉 Register Block Style https://developer.wordpress.org/reference/functions/register_block_style/
👉 WP Helpers https://wphelpers.dev/icons
👉 SVG URL Encoder https://yoksel.github.io/url-encoder/
👉 Superlist Block https://wordpress.org/plugins/superlist-block/

Transcript 

Hey, welcome. So today we’re gonna do a quick, quick demo of how to register a block style in Gutenberg. A little warning, I had done an earlier version of this video that I never released where I did it with a full build process. I had WordPress scripts running, I had SAS compiling, I had all this stuff and it was interesting.

And I think normally when I do block styles, I’m in the context of a large theme and I’m doing a lot of that work anyway, so it kind of made sense to naturally do that. But I got to the end of recording that video and I thought, man, this is something that’s just so simple and doesn’t require build process at all.

I kinda wanted to come back and do this version and I don’t know if I’ll ever release that video. If I do, I’ll stick a link to it. So we’re gonna do registering a block style, and we’re gonna do it as simple as possible. So let’s start with what is a block style? To get a sense of what a block style is, I’m just gonna insert a image into this post right here and let’s click on it.

If I go over to the styles tab in the inspector, I can see block styles right here, and when I hover over them, I get this kind of nice preview. A block style is essentially adding a class to the block and then that class has some extra styles to it that you can add. So if I put the rounded on here, all that’s really happening is a class is being added to the image and then some styles are loading to give it that extra style Block styles are super handy.

They’re also a little bit limiting cuz you can only pick one at a time. So if you’re interested in doing. Kind of multiple styles, layering or different options. I have a separate video about block settings that gives you a lot more of that freedom, but block styles are pretty handy for just very quickly giving your website or your client’s website a little bit of variation.

So the block style we’re gonna do today is for the list block. So not the, I’m in a list item block, but I’m gonna click to that parent list block. You can see there’s no other settings, there’s no styles yet. We’re gonna register a style and then we’re going to give it a little bit of design. The function that we’re gonna be using is called Register Block Style.

What’s really interesting about Register Block Style is it’s one of the very few functions that’s available in PHP and JavaScript, so, so like I said, I had done a version of this where I used the JavaScript Register block style, and I had a build process, and I was sort of doing all of that extra stuff.

But the fact that you can just do it in php it’s pretty handy cuz you can just make a simple, you know, one or two file plugin to just get a block style onto your site or you can stick it into your current build process. So, very handy. So we’re gonna use this registered block style function. So let’s head over to a plugin.

Okay, so here’s our plugin. I’ve got two files, well, two important files in this plugin. I have the main PHP of the plugin that’s kind of required. It has all our plugin headers, everything we need. And then I have a CSS file where we’re gonna put our styles. So the first thing we need to do is we just need to register our block style.

So let’s make a nice wrapper function for it. We’ll just call it register. Block style, and we’re just gonna use the register block style function. So the first parameter that register block style wants is the name of our block. So in this case, we’re actually gonna be modifying the core list block, but you could do any sort of block, you can even do blocks that are not in core, but we just need that name of the block.

And then the second thing it asks for is an array. And that array is gonna have a number of settings that we’re gonna set. And it’s gonna say style properties. And if I, you look here, you can kind of see that my WordPress codings. Like developer reference is showing up here and it kind of gives you some ideas of what these properties are and what different options are.

So in this case, the two that we’re mostly worried about are the name and the label. So we’re gonna start with name and we’re just gonna call it check. And that’s gonna be in the back end. And we’re gonna gonna look at what that’s for. And then label is more like, what will people see when they’re looking at it.

So we’ll do that one. Nice. Like that. And we’ll save it. And the last thing we need to do is actually add this. So I’m gonna actually just use in it for this. It’s not super critical where you hooked it into this. It actually does get a little weird depending on how you’re registering your style, style sheets, all those sorts of things.

I’m just sticking this in the beginning. And the it function, I know it’s gonna load on the front end and the back end, so it’s gonna kind of cover everything for me. So let’s just head over into the block editor and make sure that our block style for the list block is even showing up without any styling.

Okay, so we’ve reloaded the screen. Let’s go to our parent and now we can see we have two style options. Default and check. And that’s our check option. And again, we haven’t added any styles to it, but we can actually enable it if we want. So let’s head back over to the code and talk about how the styles work for a block style.

So the name here, like we said, is pretty important. I’ll just give an example. What WordPress is always gonna do is it’s gonna say is Dash style, dash, and then whatever name you gave it. So the name is gonna complete the class. That’s gonna be what’s added to our list. So we’re gonna build out our CSS to match that, but first we need to load our css.

This is where it gets a little tricky. There is a parameter right here called Style Handle, and what Style handle does is it lets you use WP Register script to register a style sheet but not load it. And then if your block style gets used, it loads that style sheet dynamically and it works really great, except that it only really works on the back end in the block editor.

It doesn’t really work on the front end. I’m not actually sure if it’s a bug, but at this point in time I cannot. And I’ve seen nobody come up with a good example of you actually getting style handle to load on the front end. The other little weird thing is if you look at the developer documentation for here, they actually call it style and not style handle.

But in a lot of the other documentation, the examples you see, it’ll say style handle. So you can use style handle, it loads it on the back end. It’s pretty handy. In this case we’re not gonna use it. We’re actually just gonna use a different method. What we’re gonna use is called WP and Q Block style.

So this is a relatively new function, so new that it actually doesn’t show it in the docks that I have loaded locally. So it’s pretty cool though. It’s very similar in format to this register block style. The difference is, is anytime the. That our core list block gets used, it’s gonna load the style sheet.

So even if the user isn’t using that that, you know, check style on a page, but they are using just a normal list, our style sheet gets loaded. It’s not the best, but I don’t think it’s that terrible. And I think there’s so many other performance things that people are doing to their sites that it’s not a huge deal, but hopefully they’ll get that style handle stuff worked out.

So it’s the same idea. We put the name of the block first and then an array. For some properties in this case, the first thing we need to do is the handle. Like what do we want our script to be referred to as when it gets kind of in queued? And in this case, I’m just gonna use the name of the plugin to keep a good eye on it.

And lastly, it needs to know the source where to find it. So in this case, I’m gonna use that plugins url and I’m gonna point to example block style css. Our file right here that we’re gonna fill out with some css. And save. Okay, so this is really all the PHP we need. I need. A style sheet that’s loaded for my list block, and then I need to register the actual style that I want.

And then inside of my style sheet, I just need to ref reference this class right here. So let’s head over to our CSS file and start writing some css. Now I chose to do a style on the list block. So what’s kind of interesting about this one is, you know, normally I’ll do something like, this is style check, right?

We wanna put all our styles in sort inside of here, you know. But I also usually wanna scope it to the block in case, I don’t know, maybe there’s another block that uses a very similar or same name of a style variant, but it’s kind of unrelated. So normally I would do something like WP Block list. To reference that, that’s the block that I want.

What’s a little unique about the list block is when I select the list block and I find it here, it’s a an ol or a ul, an unordered list or an ordered list. It has this class WP block list. That’s the, the kind of format for how blocks are given classes in WordPress. That’s usually pretty normal.

It’s usually a reliable way to scope things. However, with some of these really basic semantic blocks, like lists and paragraphs and stuff, you don’t actually get those on the front end of the website. So if I head over to the front end and I inspect this area, There’s actually no classes on it at all. So that’s something to keep in mind when you’re building this out.

You wanna make sure that you’re actually getting the correct element, and you can’t always rely on those WordPress block classes. So in this case, I’m just gonna scope it to an unordered list. If it’s an ordered list, I kind of don’t want it, and that kind of works for me. The first kind of pass I took at this is, you know, essentially I want a check variant of a list.

I want a style wear instead of bullets. It’s little check marks. The easiest way to do that is what’s called list style image, and we could just get an image of a check mark and use that. What we’re gonna do is head over to this WordPress icons library. This is the default WordPress icon pack that comes with Gutenberg.

This is actually a little like landing page that we built to help us kind of search for specific icons. We could do this with bootstrap material. Any other icon library. I’m just using WordPress. I’m filtering for check, and this is the icon that I want. What I’m gonna do is I’m gonna copy the SVG code and then I’m gonna open up just one of these like URL encoders, just a website I Googled for it.

You put in your SVG and it kind of gives you like the different coded versions of it here. So it’s just doing all that URL encoding for us. Just saves us a little time. So I’m gonna copy this one right here. Let’s head back into our style sheet. I’m gonna paste it except I don’t need this background image part.

I just want the image url. And save it. So what we’re basically saying is if an owner list on our website has the IS style check, then instead of a regular bullet, we’re gonna get this little image right here. So let’s take a look and see if it works. All right, let’s select our list. Let’s head over to our check design and turn it on and boom.

There we go. We have our little check marks showing up here, so it works. It doesn’t work Perfect because they’re about the size of that bullet, so they’re really tiny. But you can see that we’re kind of getting closer, right? We have our list, and if we want, we can have a regular bullet list or we can have that check mark.

But let’s do a little extra styling to make those check marks look a little bit better. What I’m gonna do instead is, We’re gonna turn off the styles and we’re gonna add our own. So we’re gonna use the before element. So we’ve turned off the bullets. We’re gonna use the before element, and what we’re actually gonna use is the content.

So, Attribute. And then inside, we’re actually going to use the same code right here. And then we’ll just do a little display inline block so that the before kind of pseudo element sits right in front of the content, basically where, you know, that check mark would’ve been. And then we’ll just give it some sizes.

This is probably gonna depend on the site that you’re working on. It’s gonna depend on. You know what other styles and designs you might have on your list. So something to kinda keep in mind. I’m just doing some basic styles here. Let’s do a like, middle, middle, vertical line. So it kind of floats just like a bullet.

And we’ll put a little space after it. Okay. So now instead of using the image as the actual bullet, we’re just turning off the bullets. We’re gonna load it with a little before. And there we go. So we have our list. This one looks a little bit better. It’s not so tiny. You can see our style is here.

We can go into the code, we can see that before is just sitting right there, right? So I think it looks a little bit better. I would maybe do some additional styling to deal with the padding, those sorts of things. Those are kind of really up to you. But overall it’s a pretty nice little look so I can kind of style it however I want.

I got a free S v g. It looks pretty good. Let’s check the backend and make sure everything is working okay. Okay, so I just refreshed the backend and this is what I’m seeing.

Inside of our list item. It’s a little hard to see, but. There’s actually a separate div inside that handles all the text editing and that diviv has like a display block and it takes up this full width. So our little checkbox kind of has nowhere to float next to it. So it doesn’t really look that great on the back end.

And that’s why it’s kind of important to really test both back and front end. You might even have a setup where you have different styles for both. That’s possible too, but we’re just gonna do a quick little CSS fix to get it looking good. So I’m gonna start a new. Line here and I’m just gonna target that first.

Diviv, I’m not super worried about it the way the list block works in WordPress you can’t add like other content. It’s just that, that text content inside. So I know like this will pretty specifically target that Diviv and I don’t really have to worry about it messing up on the front end. If you did want a list where you could do lots of other things, there’s the super list block by my friend Aruba, which actually has a lot more features for building out lists.

So, So what I really just need to do is I need to make sure that that diviv is also an inline block, and then I also need to give it that vertical line middle so that it kind of sits in the right place. Let’s take a look and see if it worked. Okay. Reloaded our site. There we go. Okay. So we were just able to take that diviv inside that list item, and now it’s just like a nice little inline block.

And so there we go. That’s a very, very quick overview of building out a block style. Let’s just do a quick once through of all the code and see how all that worked together. So most of the work is done in this one function. I en queued a style sheet. That style sheet will only load if the core list block is on the page.

I told it, it’s called the example block style style sheet cuz that’s the name of my plugin and I told it where to find that CSS file. Then I registered my custom style for the list block where I basically said, The name is gonna be check. The label on the backend will be check. And I know that by registering that as soon as my user does it, it adds this class to any list that uses that style.

And then finally, the style sheet that I loaded, pretty simple. Just scoped it to that class that I added, did a little extra design. Super easy to turn on and off and a little extra work to make sure the backend editing experience was good. And that’s essentially building a block style with no build process, no node modules, no WordPress scripts or anything like that.

Let me know if you have any questions. Pop in the chat and I’ll be sure to put all this code on GitHub so you can look at it for yourself.