Customizing Gutenberg blocks with block styles

Block styles are a simple way to get started with Gutenberg development: With a few lines of CSS, you can build something that feels like a whole new custom block.

A few years ago, Matt Mullenweg urged us all to “Learn JavaScript Deeply.” Becoming more familiar and comfortable with JavaScript is increasingly important for those of us who build the web. In the world of WordPress, projects like Gutenberg have begun taking a major step into a JavaScript-powered future.

For designers and developers who are still getting used to these new languages and workflows, creating and customizing Gutenberg blocks can be somewhat intimidating. There are excellent toolkits like Create GutenBlock to help you get started, but even using those, building a block requires quite a bit of JavaScript familiarity. You also have to make sure you’ve got the right version of Node, learn some terminal commands, install some dependencies, etc. There’s quite a bit of up-front work necessary before you can jump in and start actually building something.

Despite these hurdles, we’ve seen an inspiring number of new block plugins surface lately: CoBlocks, and Atomic Blocks are great examples. They each add a variety of rich blocks, and truly enhance the site-building experience.

There’s a much simpler way to start customizing Gutenberg blocks though, and it’s something we haven’t seen utilized much at this point: block styles. They take only a few minutes to pick up, and mostly just require you to know CSS.

You’ve likely noticed block styles while using Gutenberg. The Quote, Pullquote, Separator, Table, and Button blocks ship with some alternate styles by default.

Block styles are an excellent but relatively unused area of Gutenberg customization. They’re a simple way to get started with Gutenberg development: With a few lines of CSS, you can build something that feels like a whole new custom block. Also, since they’re reusable across multiple sites, block styles help pave the way for a more flexible system of components that make up a site’s theme.

Technically, block styles are very simple. They’re composed of two things:

  • A few lines of JavaScript to declare the block variation and give it a custom class name.
  • CSS styles to fine-tune the appearance.

That’s it. A block style is a custom block class, with some styles applied.


A block style can be implemented anywhere you can enqueue a little JavaScript and some CSS. For this example, I’m going to focus on implementing a custom block style via a plugin. One of the benefits of using a plugin is that it’s not tied to the user’s theme. This allows your block style to be used across any site, running any theme — as if you had built an entirely new custom block.

The first step to implementing block styles is to create a few files:

  • index.php to set up the plugin and enqueue the other files
  • blocks.js to declare the block style
  • style.css to house the actual styles


By default, index.php just needs to initialize the plugin with a DocBloc, and enqueue the JavaScript and CSS files:

* Plugin Name: Block Styles

* Enqueue JavaScript
function block_styles_enqueue_javascript() {
wp_enqueue_script( 'block-styles-script',
plugins_url( 'block.js', FILE ),
array( 'wp-blocks')
add_action( 'enqueue_block_editor_assets', 'block_styles_enqueue_javascript' );

* Enqueue Stylesheet
function block_styles_enqueue_stylesheet() {
wp_enqueue_style( 'block-styles-stylesheet',
plugins_url( 'style.css', FILE )
add_action( 'enqueue_block_assets', 'block_styles_enqueue_stylesheet' );


The JavaScript file is where you’ll let Gutenberg know you’re declaring a new Block Style. That requires a few lines of code:

wp.blocks.registerBlockStyle( 'core/paragraph', {
name: 'blue-paragraph',
label: 'Blue Paragraph'
} );

The first line tells Gutenberg which existing block to start with. In this example, we are going to create a block style for the Paragraph block. Any existing block can inherit a block style*, so if you were to target a different block, you’d change core/paragraph to the name of a different block. Technically, these names are found in the Gutenberg block source code, but they’re usually easily guessable. For example: core/cover, core/separator, etc.

The name: field on the second line here creates the custom class that’ll be assigned to the block. In this case, I’m calling it a blue-paragraph, but it can be anything you’d like. Since this will be used for a CSS class, be sure not to use any spaces.

The final field corresponds to the label for your block style. This will be shown in the interface when someone opens the “Block Styles” panel.


The last file is pretty straightforward. Use the custom class name you created in block.js (along with a is-style- prefix), and insert your styles inside:

.is-style-blue-paragraph {
// Custom CSS styles go here.

Your styles here will build off of the default block styles, and will be loaded in before a theme’s editor styles. So be sure to keep your selectors specific enough to override those potentially competing styles.

Block Styles Plugin Boilerplate

To help you get started, I’ve created a GitHub repository that you can clone and use to get started. It contains the three files detailed above, along with some light documentation.

Out of the box, the repository is a small plugin that adds a “Blue Paragraph” block style to the Paragraph block:

With a few small adjustments, it’s possible to change this into something drastically different. There’s another branch on that GitHub repository that includes a Music theme-style cover block variant:

I’ve included a third branch that adds a somewhat ridiculous animation to the text (or emoji) inside of a Cover block:

Both of these are accomplished by changing about a dozen lines of code in the repo. They took minutes to create, and work across any site that uses Gutenberg, regardless of the theme it’s using.

What will you create?

Block styles are ripe with possibility. I’d love to see a CSS Zen Garden-style plugin someday that showcases dozens of different ways to customize blocks through block styles.

In the meantime, have you built something cool using block styles? If so, I’d love to hear about it. Please share your explorations in the comments.

*Note: At the time of writing, blocks that accept InnerBlocks (like the Media & Text and Column blocks) have a bug which causes them to crash when custom styles are assigned. There’s an open issue on GitHub to address this.

Author: Kjell Reigstad

Designer in Boston. I spend my days proudly working at Automattic.

2 thoughts on “Customizing Gutenberg blocks with block styles”

  1. Block variations is really powerful. With a single CSS class, we can make a lot of things with just CSS. I’ve seen that a lot with simple themes on CSS is more powerful than we think.

    Just a question: are block variations allowed in themes on, or they have to be in plugins?

    1. Just a question: are block variations allowed in themes on, or they have to be in plugins?

      They are allowed! In fact, the theme review team recently added a new “Block Editor Styles” tag to the repo, so you can filter by themes that include them.

      EDIT: After further discussion with the theme review folks, the block-styles tag is actually intended for just general block styles (as in: the theme provides styles for all the default Gutenberg blocks). But Block Styles should be allowed under their current guidelines. ( slack discussion)

Comments are closed.