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.

You have three places you can put your custom CSS, in order of recommendation:

• A block stylesheet
• The css property in theme.json
• Your theme’s main stylesheet (e.g. style.css)

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.