Accordion Block

The Accordion block lets you organize content into expandable rows that can be toggled open and closed. It’s designed to reduce page length, manage complex information, and improve readability — especially when content is grouped by topic.

Accordions are commonly used for FAQs, product specifications, long-form content, and any scenario where readers benefit from scanning headings first, then expanding what’s relevant to them.

Why use the Accordion block

Use the Accordion block when you want to:

  • Reduce visual clutter on long or information-heavy pages
  • Let readers control how much content they see at once
  • Organize grouped content into expandable sections
  • Present FAQs or structured lists of related topics
  • Improve mobile usability by minimizing scrolling

Accordion items keep pages scannable while still allowing you to include rich, structured content.

How to use the block

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

Once the block is added, editors typically:

  • Add or edit Accordion items
  • Enter clear, descriptive text in each Accordion Heading
  • Build content inside each Accordion Panel using inner blocks
  • Choose the Heading level (H1–H6) at the Accordion block level. This applies to all Accordion Headings within that block.

Each Accordion block contains:

  • One or more Accordion items
  • Each Accordion item includes:
  • An Accordion Heading (the clickable row label)
  • An Accordion Panel (the expandable content area)

You can view and manage this structure in List View, which is especially helpful when working with multiple items.

Adding additional accordion items

Each Accordion item functions as a single expandable row.

There are several ways to add another item:

  • Select an existing Accordion item and press Enter on your keyboard
  • Select the Accordion block and click Add Item in the block toolbar
  • Select the Accordion item, click the three-dot menu in the toolbar or List View, and choose Add after or Add before

You can repeat this process to build a structured list of expandable sections.

Building content inside the accordion panel

The Accordion Panel supports inner blocks, which means you can add any supported block inside it. Common blocks used inside Accordion Panels include Paragraph blocks, Image blocks, List blocks, and Buttons.

While any block can technically be added, simpler blocks typically work best. Overly complex layouts inside panels can reduce readability and make content harder to manage.

Keep each Accordion item focused on a single topic to improve clarity.

Block toolbar

Toolbar options depend on which part of the Accordion you have selected.

Accordion block

When the Accordion block is selected, the block toolbar includes:

  • Block width: Adjust how wide the Accordion appears within the layout.
  • Heading level (H1–H6): Sets the semantic heading level for all Accordion Headings in this block.
  • Add Item: Adds a new Accordion Item to the block.

Accordion heading block

When the Accordion Heading is selected, the block toolbar includes basic formatting options for Bold and Italic. These formatting options should be used sparingly. Headings work best when they’re clear and consistent.

Accordion panel block

The Accordion Panel does not include toolbar controls. Content styling should be handled within the individual blocks placed inside the panel.

Block settings

Block settings appear in the right sidebar while the Accordion or Accordion Item is selected.

Accordion settings

These general settings will apply to the full Accordion block.

Inner blocks use content width: When disabled (recommended in most cases), the Accordion uses the width set in the block toolbar. When enabled, you can define a custom pixel width for the block.

Auto close: When enabled, opening one Accordion Item will automatically close any other open item in the same Accordion block.

Show icon: The toggle icon can be displayed or hidden.

Icon position: The toggle icon can be positioned to the left or right side.

Accordion item settings

These settings are specific to each individual Accordion item.

Open by default: This Accordion Item will be expanded when the page first loads. This can be enabled on multiple items, but in most cases it’s best to use it for only one item in a set to maintain scannability.

Block styles

The Styles tab includes visual controls for the Accordion, Accordion Item, Accordion Heading, and Accordion Panel. Available style options may include: Font color, Font size, Padding, Margin

These controls affect appearance only — not structure or behavior.

In most cases, it’s recommended to rely on the default styles and instead style individual blocks inside the Accordion Panel (such as Paragraph or Image blocks). This keeps layouts more flexible and consistent.

Accessibility and content structure

Accordion items are interactive elements that show and hide content. The interaction behavior is handled automatically.

To support accessibility and usability:

  • Write clear, descriptive Accordion Headings
  • Avoid vague labels like “More” or “Click here”
  • Keep each heading concise and meaningful

Readers — including those using screen readers or keyboards — should understand what each section contains before expanding it. Clear headings make that possible.

Heading level matters

The Heading level selected in the Accordion block toolbar applies to all Accordion Headings. Choose a level that fits within the overall page hierarchy.

For example:

  • If the Accordion appears under an H2 section, use H3 for the Accordion Headings.
  • Avoid skipping heading levels.

Choose heading levels based on structure — not visual size.

Tips for editors

Write headings that make sense on their own

Think of each Accordion Heading as a question or a clear topic label. Readers should understand what they’ll see when they expand it.

Keep styling consistent within a set

Use consistent font size and color across all headings in the same Accordion. Consistency improves scannability and visual clarity.

Don’t hide critical information

If content is essential to understanding the page, it may not belong inside a collapsed panel. Accordions work best for supporting or secondary information.

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