Details Block

The Details block lets you show and hide content within a single expandable section. In its closed state, it keeps pages easier to scan. When expanded, it reveals additional content for readers who want more context or supporting information.

If you need multiple expandable items grouped together, use the Accordion block instead.

Start here: watch the walkthrough (6 minutes)

Why use the Details block

Use the Details block when you want to:

  • Provide optional supporting information without interrupting the main content flow
  • Add clarification, definitions, or disclaimers
  • Offer additional context that not every reader needs
  • Keep long pages more scannable by hiding secondary or optional content

Because the block uses native HTML semantics, it also provides built-in accessibility support for expandable content.

How to use the block

Start by adding the Details block to the page. Learn how to add blocks.

Once the block is added, editors typically:

  • Add a Summary (what’s visible when the block is closed)
  • Add detail content that appears when the block is expanded
  • Insert additional blocks inside the detail area as needed
  • Adjust layout, settings, and styles to fit the page design

The Details block always contains two parts: a summary and expandable content.

Block toolbar

The block toolbar appears above the Details block when it’s selected.

Available options

  • Block width: Adjust how wide the block appears within the layout.
  • Bold and Italic: Available when the summary text is selected.

The toolbar options are intentionally minimal to keep the focus on content and structure.

Block settings

Block settings appear in the right sidebar while the Details block is selected.

Open by default

Controls whether the Details block is expanded when the page first loads.

  • Enabled: The detail content is visible immediately.
  • Disabled: Only the summary is shown until a user expands it.

Tips:

  • Use “Open by default” sparingly. Leaving most Details blocks closed helps with scannability and reduces cognitive load.
  • If the information is critical to understanding the page, consider whether it should be hidden at all.

Block styles

In Block Settings, the Styles tab includes additional controls to adjust the appearance of the Details block.

Styles

  • Default: Standard spacing and layout for a single Details block.
  • Grouped: Removes the top and bottom spacing of the block.

The Grouped style can be considered when the Details block should sit more closely with surrounding content.

Color

Changes the text color of both the summary and content blocks.

  • Use this to match brand colors or help summaries stand out.
  • Always ensure sufficient color contrast for readability and accessibility.

Size

Adjusts the font size of the summary text.

  • Larger sizes can help summaries read more like section labels.
  • Smaller sizes work better when Details blocks are used frequently on a page.

Accessibility and content structure

The Details block uses the native HTML <details> and <summary> elements.

This means:

  • Screen readers recognize it as expandable content
  • Keyboard users can open and close it easily
  • Assistive technologies understand the relationship between the summary and the hidden content

Best practices for accessibility

  • Write clear, descriptive summary text so users know what will be revealed
  • Avoid vague labels like “Click here” or “More”
  • Keep summaries concise and meaningful

The accessibility behavior is handled automatically — your main responsibility is writing clear, helpful content.

Tips for editors

Write summaries that stand on their own

The summary should clearly describe what’s inside. Think of it as a question, topic, or promise of what the expanded content will deliver.

Use inner blocks intentionally

The detail area can contain any block, including paragraphs, lists, images, or even other layout blocks. Use structure to keep expanded content readable and well organized.

Use Details for supporting content

Details blocks work best for secondary or optional information. If content is essential to understanding the page, it likely shouldn’t be hidden by default.

  1. WordPress.org Details Block documentation — please note that your block may have customizations affecting functionality, appearance, or settings.