How to Add CSS Styles to a Gutenberg Block

This is the result of how our custom block is going to look by the end of this lesson:

You can also download source files from the video using the link below:

Sorry, but you don’t have access to the source files. Sign in or buy the course.

Using Inline CSS Styles in Custom Gutenberg Blocks

Before I show you how to include CSS files into Gutenberg blocks, I would like to show you how you can use inline CSS real quick.

By the way, we will work with inline CSS more thoroughly anyway in the lesson about block color settings. As for now, I am just showing you the basics of how it works.

For example, let’s say I’d like to set the background color for my Gutenberg block. How can I achieve that with inline CSS?

Let’s start with the edit() method:

import { useBlockProps } from '@wordpress/block-editor';

export default function Edit() {

	const inlineStyles = {
		backgroundColor: '#f4faff'
	}
			
	return (
		<div { ...useBlockProps( { style: inlineStyles } ) }>
			...

Then, the save() method:

import { useBlockProps } from '@wordpress/block-editor';

export default function Save() {
	
	const inlineStyles = {
		backgroundColor: '#f4faff'
	}
	
	return (
		<div {...useBlockProps.save( { style: inlineStyles } )}>
		...

That’s pretty much it.

How to Include CSS (and SCSS) Files to Gutenberg Blocks

Now comes the interesting part of the lesson.

Quite a long time ago, if we wanted to enqueue a CSS file to a block, we had to use a special hook – enqueue_block_editor_assets and the wp_enqueue_style() function inside it. Is this method still working? Yes, of course, but I am sure that it would be better to use the block.json file for that purpose right now.

In order to do that, we need to add paths to the CSS files to block.json:

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "rudr/subscription",
  
	...
	
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style-index.css"
}

So far, we have two more parameters in the block.json file for now:

• editorStyle – The CSS rules from this file will be applied to the block in the editor part only.
• style – The CSS rules from this file will be added to both the Block Editor part and the site front end part. However, on the website, the rules will appear in the <style> tag, not as an included CSS file.

There is also one important moment about these files we need to keep in mind. Are we going to create them in the build folder and work with them there? Of course, not! In the build folder, they should be minified and stuff. So, we will create them in the src folder then. However, if you want the CSS files to be automatically processed by @wordpress/scripts and appear inside the build folder, you need to import them inside the JavaScript entry point file, which is, in our case, /src/index.js.

import './editor.scss'
import './style.scss'
import './somecustomstyle.scss'

Have you noticed something odd here? Yes, indeed, I am using SCSS files but not regular CSS files over here. And that’s another amazing thing about @wordpress/scripts – you can feel free to write styles for your custom Gutenberg block using SCSS, and as a result, everything will be compiled into regular CSS and also minified.

Another important thing we need to discuss is the names of stylesheet files you’re using inside the src folder. Depending on the file name, it will be compiled into either index.css or style-index.css, for example:

• style-index.css – This file is generated from the style.scss (or style.css) file from the src folder. If there is no such file, it won’t be created.
• index.css – This file is combined from all the other CSS/SCSS files in the src folder. For example, in our case, it will be editor.scss and somecustomstyle.scss files.

The block.json file configuration also allows us to load an already registered CSS file. In the next chapter, I will show you how you can do that.

Include an already registered stylesheet or multiple stylesheets

Both editorStyle and style parameters accept an array of values. An array means that we can include multiple CSS files with a single parameter.

{ 
	"style": [ 
		"file:./build/style-index.css",
		"misha-style"
	]
}

Everything should be clear with the first array element now, but what misha-style is?

Yes, it is a handle of any pre-registered CSS file. So you need to register misha-style first.

add_action( 'enqueue_block_assets', function() {

	wp_register_style(
		'misha-style',
		plugin_dir_url( __FILE__ ) . 'assets/misha.css',
		array(),
		filemtime( plugin_dir_path( __FILE__ ) . 'assets/misha.css' )
	);

} );

Please keep in mind that the content of the misha.css file won’t be inserted directly between the <style> tags in the page HTML; the file is going to be included as usual.

Using enqueue_block_assets instead of block.json

I think, I am certain that I do not recommend you to use this method to add CSS to your Gutenberg blocks; however, maybe in your particular case, it is the only way, so I decided to mention it here as well.

This method was used widely and was the only way before the block.json file appeared.

So, we used wp_enqueue_style() and wp_register_style() functions as usual, plus the enqueue_block_editor_assets hook if we wanted to add CSS to the block editor part, or the enqueue_block_assets hook – for both the website front-end and editor parts.

Our code could look something like this:

add_action( 'enqueue_block_editor_assets', function() {
	
	wp_enqueue_style(
		'misha-style-1',
		plugin_dir_url( __FILE__ ) . 'build/index.css',
		array(),
		filemtime( plugin_dir_path( __FILE__ ) . 'build/index.css' )
	);

} );

add_action( 'enqueue_block_assets', function() {

	wp_enqueue_style(
		'misha-style-2',
		plugin_dir_url( __FILE__ ) . 'build/style-index.css',
		array(),
		filemtime( plugin_dir_path( __FILE__ ) . 'build/style-index.css' )
	);

} );

That’s pretty much everything I wanted to show you about including CSS styles to Gutenberg blocks. You can always download the source files of the block using the link below:

However, if you’d like me to describe how block style variations work, please let me know in the comments section below.

Gutenberg Block Development

Misha Rudrastyh

Hey guys and welcome to my website. For more than 15 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X