TinjureWP

Creating Custom Block and Style Variations for a WordPress Block Theme

·

,

In a previous guide, I discussed Global Styles settings for WordPress block themes. I covered how to configure these settings, from enabling editor features and controls to defining theme-wide CSS and customizing the appearance of specific blocks. Since then, significant progress has been made in adding new features, such as block shadows, theme.json updates, extra block supports, and more.

Recent WordPress releases have begun adding block-level styling enhancement features such as block variations, section styling, and block-style variations. Much of the available information is scattered across individual articles on the WordPress Developer Blog, field guides, and dev-notes.

In this article, you’ll find a concise overview of block variations and block-level style variations, including the latest updates on color and typography variations, and section styling, while guiding readers to the original articles for a more comprehensive dive into the subject.

Section 1: The Block Variation API

The Block Variation API, first introduced with WordPress 5.4, allows users to register variations of any core block and customize its structure to set up initial custom attributes and include inner blocks as well. Similar to core blocks, the block variations are visible in the block inserter.

Below is a screenshot of the WordPress core Social Icon block, which offers multiple variations, allowing users to select from a wide array of social sites.

Here is an example of Embed block variation JSON partial file lifted from the WordPress Core Blog:

variations: [
  {
    name: 'wordpress',
    isDefault: true,
    title: __( 'WordPress' ),
    description: __( 'Code is poetry!' ),
    icon: WordPressIcon,
    attributes: { providerNameSlug: 'wordpress' },
  },
  {
    name: 'google',
    title: __( 'Google' ),
    icon: GoogleIcon,
    attributes: { providerNameSlug: 'google' },
  },
  {
    name: 'twitter',
    title: __( 'Twitter' ),
    icon: TwitterIcon,
    attributes: { providerNameSlug: 'twitter' },
    keywords: [ __('tweet') ],
  },
],

For definitions of the object fields used in the example, please visit the original article. Below are links to code examples for other block variations from the Gutenberg Block Library:

  • Cover (view code)
  • Embed (view code)
  • Column (view code)
  • Form-input (view code)
  • Form (view code)
  • Group (view code)
  • Post date ( view code)
  • Post Navigation (view code)
  • Query (view code)
  • Search ( view code)
  • Social (view code)
  • Template Part (view code)

Using the code examples above, you can create your own variation of any default block from the block library. Here are a few examples of use cases for creating block variations:

  • The WordPress Theme Handbook provides a ready-to-use example of creating Spacer block variations, with clear explanations for each step.
  • On Rich Tabor’s website, you’ll find a CoBlocks form block example that lets users choose between a traditional contact form, an RSVP form, or an appointment booking form.
  • The WP Engine website provides an example of how to create a Search block variation specifically for searching Podcast post types.
  • The Full Site Editing website offers an example of how to create a Full Width group block variation, including how to register the block variation and set it as the default.

For demonstration purposes in this article, I created a child theme based on Twenty Twenty-Four and organized the file structure according to the guidelines outlined in the WordPress Developer Blog.

assets/
  - blocks/
    - js
      - .. .js

The Block Variations are registered in the block theme’s functions.php file using JavaScript.

The Theme Handbook recommends registering block style variations in a theme’s functions.php file and provides a sample structure using an action hook enqueue_block_editor_assets and the wp_enqueue_script() function.

Note: In the next section, you will learn about other methods for registering multiple files into a block theme.

Below is a use-case example of loading an assets/block/js/block-variations.js file using the wp_enqueue_script() function in a TT4 child theme’s functions.php file.

add_action( 'enqueue_block_editor_assets', 'tt4child_enqueue_block_variations' );
function tt4child_enqueue_block_variations() {
  wp_enqueue_script(
    'tt4child-block-variations',
    get_theme_file_uri( 'assets/block/js/block-variations.js' ),
    array( 
      'wp-blocks', 
      'wp-dom-ready',
      'wp-i18n'
    ),
    wp_get_theme()->get( 'Version' ),
    true
  );
}

The next step is to add the Block Variation JavaScript file. Below are code snippets showing how to add a full-width variation of the Media & Text block to the theme’s assets/block/js/ folder, as described in this WordPress Developer Blog article.

wp.blocks.registerBlockVariation(
  'core/media-text',
  {
    name: 'media-text-full',
    title: 'Media & Text Full Width',
    attributes: {
      align: 'full',
      backgroundColor: 'tertiary'
    },
    // isDefault: true 
  }
);

Now, from your theme’s Post Editor, click the block inserter at the top left corner and search for “media.” You will notice the new “Media & Text Full Width” variation block along with the default “Media & Text” block in the search results below. When you use the “/med” shortcut in your post editor, it will also display both the default and variation Media & Text blocks.

If you insert the “Media & Text Full Width” block and add an image from the media library or upload one, then add some text in the right column, the layout will display as full-width as expected.

In this demo example, the desired full-length feature can also be achieved using a no-code approach by simply placing the Media & Text block inside a group block and setting it to the desired layout.

So, what are the best practices for creating a block variation or block style variation? Justin Tadlock of Autommatic suggests that users should create a block variation only if it is necessary to adjust a block’s settings to appear differently when a user adds it to a post. Otherwise, it’s generally best to create a custom block style to make desired changes in the block’s appearance using theme.json styles or CSS.

In the next section, let’s briefly look at how to create and use block style variations to customize the display appearance of any default blocks.

Section 2: Creating block style variations

The Global Style Variations feature, introduced in WordPress 6.6, allows users to change the appearance of their block theme using theme.json style variation preset definitions. This feature is available as a style option in the settings sidebar panel.

Theme style variation is discussed in detail in a previous CSS-Tricks article. Here, we are focusing on customizing individual block styles, which are referred to as Block Style Variations or Custom Block Styles. One common example of block style variation is the buttons block (shown below).

Here are some examples of core blocks with built-in style variations.

  • Button [Fill (default), Squared]
  • Quote [ Left border (default), Plain]
  • Image [Square (default), Rounded]
  • Table [Bordered (default), border-less stripes]
  • Separator [Short (default), Wide line, Dots]
  • Social Icon [Default, Logos only, Pill shape]

Theme authors can add and customize core block styles to offer additional style variations to their users, such as the Twenty Twenty-Four theme.

You can modify the appearance of any core blocks by adding custom CSS definitions directly to the style.css file, similar to classic themes. However, this isn’t usually the best practice. If you check out default WordPress block themes or those created by Automattic developers, you’ll notice that the style.css file is often nearly empty. It’s typically reserved for CSS properties that aren’t available in the Gutenberg editor or are still being developed. For better performance, even these small custom CSS snippets are often placed in the theme’s assets folder or directly in the theme.json file.

The easiest way to modify the appearance of blocks is by using Style Book, a low-code feature introduced in WordPress 6.2. Style Book allows users to set styles for an entire site, modify specific blocks, or create style variations (both global and per block) through the Site Editor, all without writing any code.

The screenshot below demonstrates how to add custom CSS for block styles in the Additional CSS panel, which you can find under the Styles actions (three dots) menu, located next to the style book eye icon on the left panel.

For more information on using Style Book, check out this article on the WordPress Develop Blog and this Using the Style Book video.

For more advanced users, the Theme Handbook and other WordPress documentation recommend adding custom global or per-block styling using PHP, JavaScript, or the theme.json file, which are described in the next section.

The custom CSS features introduced in WordPress 6.2 allow users to add CSS directly in the Styles interface in the Site Editor and in theme.json. This can be achieved in multiple ways, such as adding custom CSS definitions to a block via the Styles sidebar in the Site Editor.

In the demo screenshot below, the background color of the pullquote block has been changed to gold using the Additional CSS sidebar panel.

Custom CSS can also be added per block in the theme.json file as a string in styles.blocks.block.css.

"styles": {
  "blocks": {
    "core/button": {
      "css": "background: purple"
    }
  }
}

Additionally, the theme.json file and the custom CSS input in global styles support the use of & for nested elements and pseudo-selectors, as demonstrated in the following Make WordPress Blog example.

"styles": {
  "blocks": {
    "core/group": {
      "css": "background:var(--wp--preset--color--base); & .cta { background:#fafafa; padding:var(--wp--preset--spacing--40); } & .wp-element-button { background-color:purple; color: white; } & .wp-element-button:hover { opacity: 0.9; }"
    }
  }
}

To learn more about using custom CSS in the theme.json file and its various practical applications, please refer to this WordPress Developer Blog article.

Registering block styles with JavaScript

The methods described in the previous section are sufficient if you only need to modify the appearance of a few blocks with custom CSS.

WordPress theme authors are familiar with registering the style.css sheet in classic themes, multiple block style sheets can be registered using similar methods in block themes.

For more advanced users, the Theme Handbook and other WordPress documentation recommend registering custom global or per block style sheets by registering with PHP, JavaScript, or theme.json file.

As far as JavaAcript is concerned, the Theme Handbook recommends registering block style variations in a theme’s functions.php file and provides a sample structure using an action hook enqueue_block_editor_assets and the wp_enqueue_script() function.

As mentioned in the previous block variation section, we loaded a JavaScript file using the exactly similar structure in the theme’s assets/js/ folder while creating a Media & Text block variation.

You can read more about loading JavaScript files in block themes in the Theme Handbook.

For a practical use case, below is an example from the Twenty Twenty-Four theme of enqueuing custom CSS using JavaScript to modify the core/button outline style variation.

// register per block styles
add_action( 'init', 'twentytwentyfour_block_stylesheets' );

function twentytwentyfour_block_stylesheets() {
  wp_enqueue_block_style( 'core/button', array(
    'handle' => 'twentytwentyfour-button-style-outline',
    'src'    => get_theme_file_uri( "assets/blocks/button-outline.css" ),
    'ver'    => wp_get_theme( get_template() )->get( 'Version' ),  
    'path'   => get_theme_file_path( "assets/blocks/button-outline.css" )
  ) );
}

Below is an example of custom CSS code from the default Twenty Twenty-Four theme’s assets/css folder that modifies the core/button outline style variation.

.wp-block-button.is-style-outline > .wp-block-button__link:not(.has-text-color, .has-background):hover {
  background-color: var(--wp--preset--color--contrast-2, var(--wp--preset--color--contrast, transparent));
  color: var(--wp--preset--color--base);
  border-color: var(--wp--preset--color--contrast-2, var(--wp--preset--color--contrast, currentColor));
}

If you were to view your button styles, button background color has been changed to tomato red color.

What if you have multiple block styles that you want to style differently? The Theme Handbook recommends organizing individual block style sheets in the theme’s assets folder to ensure better file maintenance and site performance.

Just as we organized the JavaScript files in the /assets/js folder of the TT4 child theme in the previous section, we can similarly organize multiple block style CSS files by creating a sub-folder named assets/blocks/css and adding CSS files as demonstrated below.

assets/
  - blocks/
    - css
      - button.css
      - heading.css
      - paragraph.css
      - quote.css
    - js
      - block-variations.js

This WordPress blog article already provides code snippets for enqueuing multiple files, I put into action in my TT4 child theme’s functions.php file, as shown below:

// add to functions.php file
add_action( 'init', 'tt4child_enqueue_block_styles' );

function tt4child_enqueue_block_styles() {
  // Add the block name (with namespace) for each style.
  $blocks = array(
  'core/button',
  'core/heading',
  'core/paragraph',
  'core/quote'
  );

  // Loop through each block and enqueue its styles.
  foreach ( $blocks as $block ) {

    // Replace slash with hyphen for filename.
    $slug = str_replace( '/', '-', $block );
  
    wp_enqueue_block_style( $block, array(
      'handle' => "tt4child-block-{$slug}",
      'src' => get_theme_file_uri( "assets/blocks/css/{$slug}.css" ),
      'path' => get_theme_file_path( "assets/blocks/css/{$slug}.css" )
    ));
  }
}

The example above assumes that the four block custom CSS style files, button.css, heading.css, paragraph.css and quote.css exist in the theme’s assets/css/ sub-folder.

Registering block styles with PHP

Block style sheets can be registered in a block theme’s functions.php file using the register_block_style() function using the following structure:

register_block_style( 
  string $block_name, 
  array $style_properties
): bool

The function accepts two parameters  $block_name and $block_style_namereturns true or false.

The default Twenty Twenty-Four theme registers several block style variations in its functions.php file. Below is an example of registering a core/list block style variation, taken from it.

add_action( 'init', 'twentytwentyfour_block_styles' );

register_block_style(
  'core/list',
   array(
      'name' => 'checkmark-list',
      'label' => __( 'Checkmark', 'twentytwentyfour' ),
      /*
      * Styles for the custom checkmark list block style
      * https://github.com/WordPress/gutenberg/issues/51480
       */
       'inline_style' => '
       ul.is-style-checkmark-list {
         list-style-type: "\2713";
       }

      ul.is-style-checkmark-list li {
         padding-inline-start: 1ch;
      }',
    )
);

Although it’s recommended to add custom CSS using a block stylesheet, inline styling can be used if there are only a few lines of CSS code, as shown in the example above.

Registering block styles in theme.json

The Block Variation property can be added directly via the theme.json file, under the styles/blocks section in core/{blockName}. The following example from the Theme Handbook shows how to modify the Outline style of the core Button block to include a drop-shadow, creating a double-border effect.

{
    "version": 2,
    "styles": {
      "blocks": {
        "core/button": {
          "variations": {

            "outline": {
              "border": {
                  "color": "var:preset|color|black",
                  "radius": "0",
                  "style": "solid",
                  "width": "3px"
              },
              "shadow": "var:preset|shadow|outlined",
              "spacing": {
                "padding": {
                  "top": "0.5rem",
                  "bottom": "0.5rem",
                  "left": "1.5rem",
                  "right": "1.5rem"
                }
              }
            }
          }
        }
      }
    }
  }
}

If you view the theme.json file of the Twenty Twenty-Four theme, you’ll notice that the Quote block style has been customized by adding custom CSS and including the variation field to modify the core Quote block’s default plain style variation.

The screenshot above shows the default quote block with a contrast-2 background color and rounded corners, as well as its Plain variation, which has no background color.

In the next section, we will briefly look at the Section Styles and other enhanced features introduced in the recent WordPress 6.6 release.

Section 3: Section styles and enhanced block style variations

WordPress 6.7 includes several very handy enhancements, such as Section Styles and restructured global style variation features to filter out Color and Typography Settings presets.

Registering style variations

Prior to WordPress 6.6, global style JSON variation files could be registered in a block theme’s /styles folder. Now, users can organize their style variations into global, block, color, and typography in sub-folders (see below) within the block theme’s /styles folder.

Below is an example of a suggested block theme’s /styles folder structure from the WordPress Developer Blog.

/styles
/block or /section
/color
/global or /theme
/typography

Section styling

Section Styles are an extension of block styles or block style variations that allow for the styling of inner blocks and elements.

Similar to block style variations discussed in previous sections, Sections Style can be registered using both JSON files and PHP with the register_block_style() function.

Below is an example from WordPress Core that registers a Section Style using JSON partial files. The required properties for Section Style JSON partials are top-level properties: name, slug, and blockTypes. The blockTypes property includes an array of block types to which the block style variation can be applied.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Variation A",
  "slug": "variation-a",
  "blockTypes": [ "core/group", "core/columns", "core/media-text" ],
  "styles": {
    "color": {
      "background": "#eed8d3",
      "text": "#201819"
    },
    "elements": {
      "heading": {
        "color": {
          "text": "#201819"
        }
      }
    },
    "blocks": {
      "core/group": {
        "color": {
          "background": "#825f58",
          "text": "#eed8d3"
        },
      "elements": {
        "heading": {
          "color": {
            "text": "#eed8d3"
          }
        }
      }
    }
  }
}

When I ran the code snippets on my test site’s TT4 Child theme as /styles/section/variation-a.json, the “Variation A” style button is displayed in the Styles panel on the sidebar. Selecting this button changes the background color of the Column and Group block, as illustrated in the screenshot below.

The following WordPress Core example demonstrates how to programmatically register Section Styles using the register_block_style() function in the theme’s PHP functions file.

register_block_style(
  array( 'core/group', 'core/columns' ),
  array(
    'name' => 'green',
    'label' => __( 'Green' ),
    'style_data' => array(
      'color' => array(
        'background' => '#4f6f52',
        'text' => '#d2e3c8',
      ),
      'blocks' => array(
        'core/group' => array(
          'color' => array(
            'background' => '#739072',
            'text' => '#e3eedd',
          ),
        ),
      ),
      'elements' => array(
        'link' => array(
          'color' => array(
            'text' => '#ead196',
          ),
          ':hover' => array(
            'color' => array(
              'text' => '#ebd9b4',
            ),
          ),
        ),
      ),
    ),
  )
)

In the example above, the first parameter, $block_name, accepts an array of block types. The second parameter, $style_properties, includes a new style_data key, which expects an array formatted similarly to its JSON counterpart.

You can find a more detailed explanation and practical use case examples of Section Styles with nested elements in this recent WordPress Developer Blog article.

Style presets and typography

WordPress 6.6 introduces a new feature enabling theme authors to incorporate only subset of color and typography preset style variations with a limited scope, without applying the full range of changes that a style variation would typically include.

This Assembler theme from the Automattic team contains 46 color and 15 typeset variations, as an excellent use case example showcasing how more than 700 unique styles can be easily mixed and matched with just a click of a button. This short video demonstrates a few of these variations, with a more detailed explanation available on Rich Tabor’s personal website.

When registered, they appear as new options in the Appearance > Editor > Styles sidebar panel and other locations. The color presets and typography typesets appear separately as ‘Pallets’ and ‘Typography’ in the Styles section of the Site Editor.

Below is a screenshot of the Styles sidebar from the Twenty Twenty-Four theme, displaying theme styles, color palettes, and typography typesets.

A recent WordPress Developer Blog article provides details on how to register color presets and typography typeset variations, along with use case examples. If you want to dive deeper into the history and context of Section Styles, color presets and typesets, visit GitHub issues #57537.

Additional enhancement features

The Block variations and Block Style variations of core blocks discussed in this article and other similar resources in the WordPress documentation or blog posts may not address all your needs. If you find this to be the case, you may consider exploring additional options for extending existing blocks as detailed in a recent WordPress Developer Blog article.

If these options still don’t meet your requirements, you may need to create a custom block from scratch. Detailed guidance on how to do this is available in the Block Editor Handbook.

Wrapping up

This article summarizes Block Variation and Block Style Variation, providing a few examples sourced from WordPress documentation. Instead of rehashing what is already available, the purpose is to direct readers to the original resources for more in-depth information, which is detailed in the subsequent section.

Additional resources

More on WordPress