Lede Docs

Accordion block

The Accordion block stacks content into sections that readers open and close. Each section has a heading that works as a button: click it and the content underneath opens, click it again and it closes. It suits FAQs, reference material and anything readers want to scan before they dive in.

Accordion is WordPress’s own block. Find it in the Design category of the block inserter, or type /accordion. It’s available in posts and pages, including your homepage. It isn’t available in newsletters.

How an accordion is put together

An accordion is four blocks nested inside each other. You’ll see their names in List View and at the top of the sidebar, and each one has its own settings:

  • Accordion is the whole block. Settings that apply to every section live here.
  • Accordion Item is one section: a heading and a panel.
  • Accordion Heading is the clickable title of a section.
  • Accordion Panel is the content that opens under the heading.

List View is the easiest way to select the part you want. This matters most for an Accordion Item, because clicking in the editor usually selects the heading or panel inside it.

Adding sections and content

A new accordion starts with one item. Type its title where it says Accordion title, then click into the panel below it to add content.

To add an item, select the Accordion block and click Add item in its toolbar, or click the + at the bottom of the block. To reorder items, select one and use the move arrows in its toolbar, or drag it in List View. To remove one, select the Accordion Item and delete it as you would any block.

Every item is exactly one heading and one panel. You can’t delete an item’s heading or give it a second panel.

A panel takes the same blocks you can use anywhere else in the post: paragraphs, lists, images, embeds, even another accordion. Headings are simpler. You can make words bold or italic, but a heading can’t contain a link or a line break.

In the editor, an item opens while you’re working in it, so click a heading to see and edit its panel. Items set to Open by default stay open. This is only a preview, and it doesn’t change what readers see.

Accordion settings

Select the Accordion block to find the settings that apply to every item in it.

SettingWhere to find itWhat it does
Heading levelToolbarSets the level of every heading in the accordion, from H1 to H6. The default is H3.
Add itemToolbarAdds a new item at the end of the accordion.
AlignToolbarMakes the accordion wide or full width. By default it matches your content width.
Auto-closeSidebar, Settings panelWhen a reader opens an item, any other open item in the same accordion closes. Off by default.
Show iconSidebar, Settings panelShows an icon on each heading that changes when its item opens. On by default.
Icon PositionSidebar, Settings panelPuts the icon on the Left or Right of each heading. The default is Right. Only shown when Show icon is on.
IconSidebar, Icon panelPlus, Chevron or Triangle. The default is Plus. Only shown when Show icon is on.
StyleSidebar, Styles tabDefault, Bordered, Divided or Filled.

The help text under Show icon says it displays a plus icon, but the toggle turns off whichever icon you’ve chosen.

Choose the heading level for structure, not size. Accordion headings use your site’s Extra Small heading size at every level, so changing the level doesn’t change how they look. Screen readers and search engines do use it to understand the page’s outline, so pick the level one below the section the accordion sits in. Under an H2, for example, use H3.

Set the heading level after you’ve added all your items, or choose it once more when you’re done. Items added with the + at the bottom of the block can miss a level you chose earlier. Items added with Add item in the toolbar don’t have this problem.

Icons

With Show icon on, choose an icon in the Icon panel. Each one moves when its item opens:

  • Plus turns into an ×.
  • Chevron points down, then flips to point up.
  • Triangle points right, then turns to point down.

The icon takes the heading’s text color, so it always matches the heading, in light and dark mode. Readers who have set their device to reduce motion see the icon change without the animation.

Turning Show icon off keeps your icon choice, so the same icon comes back when you turn it on again.

The Icon setting is saved as a class, has-icon-chevron or has-icon-triangle, which you’ll see under Advanced in Additional CSS class(es). Leave it there. Deleting it sets the icon back to Plus.

Block styles

Pick a style in the Styles tab. Any style works with any icon and icon position.

  • Default has no borders or background. Headings and content sit on the page, with space between items.
  • Bordered puts each item in a light outlined box with rounded corners and padding inside.
  • Divided separates items with thin lines and no space between them. It’s compact, and a classic look for an FAQ.
  • Filled puts each item on a lightly shaded background with rounded corners and padding inside.

All four use your site’s theme colors and adapt to dark mode on their own.

A style is a starting point. Any border, color or padding you set in the sidebar overrides the style’s own. The one exception is Divided, which ignores Block spacing between items because the lines replace that space.

Opening an item by default

Select an Accordion Item and turn on Open by default in its Settings panel. That item is open when the page loads, and readers can still close it. You can set this on as many items as you like.

Design controls

Each of the four blocks has its own design controls in the Styles tab, so you can style the whole accordion, one item, or a single heading or panel.

BlockDesign controlsWorth knowing
AccordionColor (text, background, gradient), background image, typography, border and radius, shadow, padding, top and bottom margin, block spacingBlock spacing sets the space between items.
Accordion ItemColor (text, background, gradient), typography, border and radius, shadow, padding, top and bottom margin, block spacingBlock spacing sets the space between the heading and the panel.
Accordion HeadingColor (text, background, gradient), typography, border and radius, shadow, paddingPadding sets the size of the clickable area.
Accordion PanelColor (text, background, gradient), typography, border and radius, shadow, padding, block spacingBlock spacing sets the space between blocks inside the panel.

How these settings combine:

  • A text color set on the Accordion or on an item applies to its headings as well as its panel text.
  • Other typography set on the Accordion, an item or a panel, such as font size, styles the panel text. Headings keep their own font, size and weight. To change those, select a heading and use its own Typography settings.
  • To give every heading the same look, style one, then use Copy styles from its options menu (⋮) and Paste styles on each of the others.

In dark mode, text and background colors you set on any part of an accordion are replaced with your dark theme’s colors, so text stays readable. Borders keep the color you chose, so pick one that shows up on both light and dark backgrounds. If your site offers dark mode, a block style is often a better choice than custom colors.

What readers see

  • Items start closed, except those set to Open by default.
  • Readers open an item by clicking its heading. Keyboard users can Tab to a heading and press Enter or Space. Screen readers announce each heading’s level and whether its item is open or closed.
  • With Auto-close on, opening an item closes the one that was open.
  • Searching the page with Ctrl+F (Cmd+F on a Mac) finds text inside closed items and opens the item with the match. Most current browsers support this. In a browser that doesn’t, readers need to open the item first.
  • Everything inside closed items is part of the page, so search engines index it.

Linking to something inside an accordion

You can link straight to content inside an item, from the same page or from anywhere else. When a reader follows the link, the item opens and the page scrolls so the content sits just below your site’s header.

  1. Select a block inside the panel, such as a paragraph or a heading.
  2. In the sidebar, open Advanced and enter a short name under HTML anchor, for example refund-policy.
  3. Link to #refund-policy from the same page. To link from anywhere else, add #refund-policy to the end of the page’s URL.

Put the anchor on a block inside the panel, not on the Accordion Heading. A link to a heading’s anchor scrolls to the heading but leaves its item closed.

Hiding an item

To hide one item without deleting it, select the Accordion Item, open its options menu (⋮) and choose Hide. Choose Omit from published content to hide it everywhere, or pick the devices to hide it on. A heading or panel can’t be hidden on its own, so hide the whole item instead.

Common uses

  • FAQs on a membership, events or support page, with each question as a heading. The Divided style suits these well.
  • Event and festival guides: lineups, set times, venue details, tickets and accessibility information, with one item per topic or per day.
  • Explainers and reference material, such as a glossary, a timeline by year, or a race-by-race election guide that readers scan for the part they need.
  • “How we reported this”: methodology, sourcing and data notes at the end of an investigation, there for readers who want them without lengthening the story.
  • Spoilers: results, endings and plot details that readers choose to reveal.
  • Staff and about pages, with a bio under each name, or your ethics, corrections and comment policies gathered on one page.

When to use something else

  • Don’t put anything every reader needs in a closed item, such as the main point of a story, a correction or a disclosure. Many readers never open them.
  • A single item rarely needs an accordion. A heading and a few paragraphs will do.
  • To let readers switch between a few alternatives on a page, try the Tabs block. Tabs are for pages only. Accordions work in posts too, and they handle long headings better on phones.

Pro tips

  • Write headings the way readers would ask. “Can I cancel my subscription?” scans better than “Cancellations.”
  • Turn on Auto-close for long accordions, so the page doesn’t keep growing as readers open items.
  • If readers might not realize the headings open, set the first item to Open by default.
  • Use Bordered or Filled to set an accordion apart from the article text around it.
  • Preview on a phone. Long headings wrap onto several lines there, so keep them short.

Was this article helpful?