WordPress.org

WordPress Developer Blog

Styles, patterns, and more with the Details block

When WordPress 6.3 bundled the Details block, I was excited. Really! I’m a theme author, so I always get excited when a new block lands in Core. Because that means I get to play with it—see what it does and how it works, and, best of all, figure out new ways to put it to work.

And I’ve been anticipating this one for years.

The Details block combines two HTML elements: <details> and <summary>. It is an HTML-native way to show and hide content: the summary part is a title that hides the details until your user clicks on it to trigger a reveal of the details.

Now, by default, it doesn’t look that impressive:

But that means WordPress has left you all kinds of room, stylistically speaking, to add your own flourishes every time you use it in a theme and make it truly your own.

There is so much you can do with it:

  • Spoiler alerts
  • Code reveals
  • Audio transcripts
  • Togglable FAQs list

In this tutorial, I will walk you through some things I have been tinkering with. Think of it as an introduction to making the block fit your theme visually, and getting it to work well with other theme features. We’ll touch on everything from custom CSS to patterns to block styles.

The underlying HTML of the Details block

Before you start tinkering with the block, make sure you understand what the HTML structure is doing, both on the front end and in the editor, where it will look like this:

<details class="wp-block-details is-layout-flow wp-block-details-is-layout-flow" open="">
	<summary>Custom summary text</summary>
	<!-- Almost any other block or markup can appear here. -->
</details>

Notice that the <details> element is a wrapper, for the <summary> element and other blocks, too. It’s hard to know from here just what your users might put in there, but they can add whatever they think they need. So if you have a good handle on the markup, you’ll have a solid approach to the design that will serve them well.

Also know that there is no way to specifically target the inner <summary> element with the default design tools in theme.json. You will need to write some custom CSS.

Customizing the Details block

From this point forward, I’ll share with you some of my customizations. But you’ll want to put your own flair on this block and make it your own.

Adding base styling

I don’t recommend leaving the Details block to its default browser styling. It’s boring, and site visitors will slide right on by. So give it a little more life, like this:

OK. That’s not a lot more life, but it’s a start.

To build this look, target styles.blocks.core/details in your theme.json file:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"styles": {
		"blocks": {
			"core/details": {
				"border": {
					"radius": "6px"
				},
				"color": {
					"text": "#0284c7",
					"background": "#f1f5f9"
				},
				"shadow": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
			}
		}
	}
}

The block supports the typical range of styling properties in theme.json, but this is also one of those times you might find theme.json pretty limiting. It will not support:

  • Directly targeting the <summary> element.
  • Customizing the transition CSS property.
  • Contextually styling the <details> element based on its open attribute.
  • Targeting nested blocks.

For those things and more, you’ll need to write your own CSS, at least if you want to do anything more advanced than what WordPress supports out of the box.

Choose what works best for your project. Then, add this custom CSS:

/* Add a custom transition when opening/closing. */
.wp-block-details {
	transition: all 0.5s ease-in-out;
}

/* Add horizontal margin to nested blocks/elements. */
.wp-block-details > :where( :not( summary ) ) {
	margin-left: 2rem;
	margin-right: 2rem;
}

/* If open, add some bottom padding to avoid content butting against the bottom. */
.wp-block-details[open] {
	padding-bottom: 2rem;
}

/* Base `summary` element styling. */
.wp-block-details summary {
	transition: all 0.5s ease-in-out;
	box-sizing: border-box;
	padding: 2rem;
	font-weight: 500;
}

/* Change the background of the `summary` element based on state. */
.wp-block-details[open] summary,
.wp-block-details summary:hover,
.wp-block-details summary:focus {
	background: #e2e8f0;
}

As you can see, nearly all of the CSS is targeting the inner <summary> element and other elements. Each CSS rule set in the above code has comments that explain what’s happening, because someone else won’t know by looking. And in three months, you probably won’t remember.

Of course, the actual design of your Details block will differ from mine. This just gives you a foundation to work from and shows that you’ll likely need to combine both theme.json and CSS to get the display and functionality that you want.

Adding a custom marker

Because the marker technically lives inside the nested <summary> element, you’ll style it with CSS—CSS pseudo-elements, to be exact. You can do that in two ways.

Targeting the ::marker pseudo-element

The <summary> element supports the ::marker CSS pseudo-element, so you can use that to change its content to any valid string.

Let’s try adding a + sign when the Details block is closed and a - sign when it is open, as shown below:

To customize the marker, add this CSS wherever you’ve put your other block CSS:

.wp-block-details summary::marker {
	content: "+ ";
}

.wp-block-details[open] summary::marker {
	content: "- "
}

Note the [open] CSS attribute selector in the code. Target that to style the Details block when it’s open.

Targeting the ::before or ::after pseudo-elements

Or, you can target either the ::before or ::after CSS pseudo-element. 

What happens if we move our custom +/- marker after the <summary> element, as below?

Now add this custom CSS to add a marker using the ::after pseudo-element:

.wp-block-details summary::marker {
	content: none;
}

.wp-block-details summary::after {
	content: " +";
	float: right;
	text-align: right;
}

.wp-block-details[open] summary::after {
	content: " -"
}

Note that the code specifically disabled the ::marker pseudo-element content so you don’t end up with two markers.

Building a FAQs pattern with the Details block

By now, I hope you’re already getting ideas for great things you can do with the Details block. It lends itself well to several different patterns.

Let’s try building a simple FAQs pattern like this:

In fact, the Twenty Twenty-Four theme ships a pattern like this (check out a live demo).

Let’s start with the Details block, pulled from the pattern. In particular, take note of the placeholder attribute for the default nested Paragraph block:

<!-- wp:details -->
<details class="wp-block-details">
	<summary><?php esc_html_e( 'Question 1?', 'themeslug' ); ?></summary>
	<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
	<p></p>
	<!-- /wp:paragraph -->
</details>
<!-- /wp:details -->

You can change this value to anything you want—for example, if you’d like to give your users a placeholder that’s specific to the pattern that you are building. In this case, the block will prompt users to “Add an answer to the question.” Pretty neat, right?

As the Block Patterns documentation will instruct, add a file named faqs.php in your theme’s /patterns folder. Then add your pattern file header metadata to it:

<?php
/**
 * Title: FAQs
 * Slug: themeslug/faqs
 * Description: Outputs a list of configurable FAQ items.
 * Categories: text
 * Keywords: faq, accordion, toggle, questions, answers
 * Viewport Width: 640
 */
?>

Configure this however you want. Just be sure to update themeslug to match your theme’s slug.

As an exercise, I recommend trying to build the pattern directly from the editor first. Then, copying and pasting it into the faqs.php file. Of course, you’ll want to internationalize any text you add inside the file. I also always recommend wrapping patterns in a container block of some sort—a Group, Row, Stack, or Cover.

But feel free to copy and paste this example code into your faqs.php file if you’re in a rush:

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 1?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 2?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 3?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->

	<!-- wp:details -->
	<details class="wp-block-details">
		<summary><?php esc_html_e( 'Question 4?', 'themeslug' ); ?></summary>
		<!-- wp:paragraph {"placeholder":"<?php esc_attr_e( 'Add an answer to the question.', 'themeslug' ); ?>"} -->
		<p></p>
		<!-- /wp:paragraph -->
	</details>
	<!-- /wp:details -->
</div>
<!-- /wp:group -->

Now you’re ready to do what it takes to make this yours—or build some new patterns around the Details block and make those patterns yours too.

Custom Details “spoiler” block style

You can use the Details block for so many things, in so many ways. It’s great for collapsible code snippets, notes, warnings, and much more.

Let’s build a block style that lets you display a spoiler alert to site visitors (this could be useful for a book review website):

For this, you’ll register the block style in PHP and follow the instructions in the Block Styles documentation. Those docs tell you to register a custom style with register_block_style().

Add this code to your theme’s functions.php file:

add_action( 'init', 'themeslug_block_style_variations' );

function themeslug_block_style_variations() {
	register_block_style( 'core/details', array(
		'name'  => 'spoiler',
		'label' => __( 'Spoiler', 'themeslug' )
	) );
}

Now, all you did there was register the style to make it show up in the Details block settings sidebar. To design it, you’ll need to add some CSS.

For now, add this code to your other block CSS:

.wp-block-details.is-style-spoiler {
	background: #ffffff;
	border-left: 5px solid #fcb900b8;
	box-shadow: 1px 1px 1px 0 #fcb90029;
}

.wp-block-details.is-style-spoiler summary {
	font-weight: bold;
	background: #fcb90029;
}

.wp-block-details.is-style-spoiler summary::marker {
	content: "⚠️ "
}

As with most examples in this post, you’ll want to add your own styling to match your theme.

Again, there are so many uses for the Details block that nobody could cover them in a single post. Or think of even a fraction of the possibilities!

Plus, I want to leave you with just enough to get your imagination running wild. So please share your implementations in the comments.

I can’t wait to see what you invent!

Props to @marybaum, @bph, and @ndiego for feedback and review on this post.

Categories: ,

9 responses to “Styles, patterns, and more with the Details block”

  1. Jan Horna Avatar

    Nice examples!

    I was waiting a long time for the Details block. I previously implemented an accordion/FAQ with the HTML block and finally changed it with the Details block. Please see the FAQ section at https://demo.bergify.com/contact/, it is available as a block pattern in my Bergify theme.

  2. DragBlock Avatar

    I am surprised that WordPress still goes along with compact blocks for everything and turns into another useless page builder.

    Will we have million blocks for every thing and bloat the whole editor like other page builders are doing?

    I suggest create only basic blocks and provide patterns for things. You don’t have to create mega blocks that have giant codes to cover every case with tones of options but only patterns which use only the codes that matter to their design.

    1. Birgit Pauli-Haack Avatar

      The smallest entity is a block, and a collection of blocks are combined into patterns, sections for templates and pages, there appears to be a lot of agreement with your idea. The performance team did some testing. You can read up about their results here: . You might not have a particular use for the Details/Summary block, there have been plenty of bloggers who need such a basic block around an HTML construct to have some styling tools with it for their site. Maybe there are specific issues you encounter, with the block editor, bugs that need to be fixed, the overall philosophy seems to align with your advice.

  3. Panos S. Avatar

    Thank you for the examples, I’ve always appriciate them! I’d love to see what else the team behind Gutenberg is thinking of releasing, but I would hate to see the editor became bloaded like other page builder plugins.

    But I do wonder; If I don’t use specific blocks, do they still load some code in visitors? I can see I can disable the blocks I am not using from displaying inside Gutenberg, but would their code load for visitors even if they are not placed in the post/page?

    1. Justin Tadlock Avatar

      Blocks and any related assets (JS, CSS, etc.) are never loaded on the front end for site visitors unless they are in use on that specific page and a particular asset is required for the front-end view. Because of the way this is all loaded under the hood, it’s highly efficient. Only the things that are necessary are loaded.

      In the editor itself, all blocks are available. So it’s very possible it could cause heavier editor page loads, particularly if using a lot of third-party block libraries. If you’re building a client site, one thing you can do is remove blocks that your client doesn’t need.

      With that said, I believe most of the core WordPress block library is well rounded at this point. We’ll still see some additional blocks in the future, but I doubt we see a ton of new additions.

  4. Mike Avatar
    Mike

    Hi! I’m a complete newbie when it comes to the CSS part of WordPress. I want to use the details block to contain filters on my shop pages, but I want them hidden by default on mobile, and expanded by default on the desktop. Can you step me through how I might do this with CSS? Thanks!

    1. Justin Tadlock Avatar

      The open/close mechanism is native to the browser based on the open attribute in the HTML. I’m not sure you can change that behavior with CSS. Well, you probably could, but that doesn’t seem like a good way of going about it. I feel like a JavaScript-based solution would be more ideal. I’m also not really sure this block is the best solution for your scenario.

  5. Peter Müller Avatar

    Just to let you know that your writing is much appreciated – here is a glossary inspired by your ideas.

    Details block plus some extra CSS (inspired by this post) and a few lines of JavaScript (*). It’s in German, but you’ll get the idea by clicking around it:

    https://einstieg-in-wp.de/glossar/

    My biggest problems were that the Details block cannot have an ID for an anchor (added a group block for that) and that the Summary apparently cannot be a link and therefore a click on it cannot change the URL and add a #hash (not solved yet).


    *
    I’m not a programmer, so the JavaScript for the behavior sort of works, but still has several shortcomings and certainly is not something to learn from. Ideas to improve it are always welcome 😉

    1. Justin Tadlock Avatar

      I’d be careful about changing the behavior of the Details/Summary with JS. It’s important to remember that this is not an accordion, so make sure anything you do takes accessibility into account and is usable by everyone.

Leave a Reply

Your email address will not be published. Required fields are marked *