Styling your WordPress Blocks

This tutorial will guide the new block developer on the process of styling the Edit component and the save function of a newly created WordPress block.

Learning outcomes

Understanding how Blocks enqueue CSS
Use the className property in JSX to apply class attributes
Add custom styling to a block
Add additional style to a block in the Block Editor

Comprehension questions

What is the name of the block.json field that represents the style sheet applied in the Block Editor?
Why should you use className and not a class in JSX elements?
What is the name of the scss file that handles the block styling?

Transcript

Hi there, and welcome to Learn WordPress.

In this tutorial, you will learn how to add styles to a custom WordPress block. If you haven’t already watched the adding blocks support to an existing plugin tutorial, I recommend watching that first, as this video will be referring to the code solutions presented in that tutorial.

In this video, we will cover how blocks enqueue CSS files, how to use class attributes in your JSX code, applying CSS to your custom block, and applying additional CSS to the block when it’s rendered in the editor.

In the original adding block support to an existing plugin tutorial, you started with a PHP shortcode plugin. While functional, the shortcode would usually also have some styling applied by way of the CSS file loaded from the plugin directory.

The code to make this happen based on the shortcode might look something like this. At the top of the plugin, a function called wpl_subscribe_shortcode_scripts is registered on the wp_enqueue_scripts action hook. And the wp_register_style function is used to register the CSS stylesheet located in the plugin’s assets/css directory.

Then at the top of the shortcode callback function, this style sheet is enqueued for rendering whenever the shortcode is used by calling the wp_enqueue_style function. If we look at the style sheet that’s enqueued, it adds a background color and some padding to the container div and applies a bold font to the header tag. This is done by applying specific styles to the class attributes of both the container div and the header element. We can see this rendered on the front end of the site when the shortcode is rendered.

There’s the shortcode and there’s the front-end rendering. And if we inspect this, we can see the HTML from the shortcode.

To add the styles to your block, you need to know where to define them. If you look at the block.json file attributes, you will see the editorStyle and style attributes defined. The values for these attributes are both files that will be created in the build directory during the build step. In this case, index.css and style-index.css. The style file is enqueued both when the block is rendered in the editor and whenever the block is rendered on the front end. The editorStyle file is enqueued when the block is rendered only in the Block Editor and can be used to add style specific to the editor experience. The style.scss file in the source directory is used create the style file. The editor.scss file in the source directory is used to create the editorStyle file. Currently, both of these files contain the scaffolded code from the previous tutorial, so we can clear them out.

Delete that and delete that.

These two files are syntactically awesome style sheets also known as Sass files. Just like the new JSX format used to create blocks transpilers into regular JavaScript during the bold step, Sass files transpile into regular CSS. These files follow the new SCSS syntax, which you can learn more about on the Sass website. Fortunately, Sass files also support regular CSS, which we’ll be using in this tutorial.

The reason for having the additional editorStyle stylesheet for your block is if you want to display different elements when the block is being added or edited in the Block Editor. For example, you might have a block that includes a select box, which allows the user to select a post which powers the block in the editor. The select box will only be displayed in the editor, but you might want to style it in some specific way. This is where the editorStyle stylesheet comes in handy.

Let’s start by styling the block. If you’ve not done this already, switch to your terminal and start the wp-scripts dev server in the plugin directory, so it watches the file changes and builds the new block output while you code.

So we will run

npm start

and confirm that it’s building. If you inspect the final HTML of the subscribe block in its current form, you will see it looks like this.

The container div’ss class attribute is generated from the name property in the block.json file and is used here because we used useBlockProps in the save function. You can make use of this class in the style.scss file so it targets the correct elements.

So it’s wp-block-wp-learn-subscribe-subscribe block. And if we switch over to our editor and paste that, then we can style the block. And we’ll just grab the styling from the original file.

This will add the background color and the padding to the container div in the block. At the same time, it would be a good idea to add the class to the header element so that we can define the specific styles to that element in our block. To do this, we need to add a className value in the save function and the Edit component where it renders the JSX. If we switch back to the browser, it’s the subscribe-header class. In our save function, update this to be className. subscribe header. And then edit. Do the same thing.

Just because JSX is closer to JavaScript and HTML, even though it looks like HTML, it uses JavaScript DOM properties instead of HTML attributes. Therefore, you use the className property here and not the HTML attributes class. Then you can update your style.scss file and add your header style.

So in our case, we’re going to copy the container and then add the subscribe-header class and then grab the styling from the original stylesheet. This will add an additional bold font to the element with the class subscribe-header. If you switch back to the terminal, we can see the build completed successfully. To see the change, you’ll need to refresh your post in the editor screen, as the build is updated the block code. Back in the editor, let’s close that, we can refresh this, and there we can see the styling.

Sometimes your browser might have cached the editor style, so you might have to do what’s known as a hard refresh. In Chrome-based browsers, you can do this by enabling dev tools, right-clicking on the Refresh button, and selecting the relevant option.

Empty cache and hard reload.

If we preview this block on the front end, we can see that the style has also been applied there. As mentioned earlier, it’s possible to add additional styles to the block when it’s rendered in the editor by adding these styles to the editor.scss file. For example, let’s say you wanted to add a red border to the block in the editor just to show where the block is situated.

So if you go and grab the class and add it to the edit.scss file, and then we’ll say border five pixels solid grid. For example, if you switch back to the terminal, you can see that the build is completed successfully again. And now you can see that the styles have been applied in the editor by refreshing the post.

Now we can see the red border around the block. However, if we view the same block on the front end, so let’s preview this again. We can see that the border color has not been applied. Congratulations, you have successfully styled your custom block.

Happy coding

Additional Resources

Practice on a private demo site

Length	9 minutes
Language	English
Subtitles	English

Suggestions

Found a typo, grammar error or outdated screenshot? Contact us.

License

CC BY-SA 4.0