Build an accordion in Gutenberg
Use Accordion to group related information into expandable panels, such as delivery details or frequently asked questions. Each Accordion item has its own title, optional subtitle and nested content. This guide is for editors using the WordPress block editor with POM active.
Add panels
- Open Pages → All Pages or Posts → All Posts and edit your content in the block editor.
- Open the block inserter and choose POM Accordion. WordPress may also offer its separate native Accordion block; choose the POM block for the theme's presentation and controls.
- Select Add panel. The new item contains a paragraph ready for writing. An empty Accordion remains empty until you add a panel.
- Enter Title and, optionally, Subtitle on the canvas or under Panel settings in the block sidebar. These fields accept plain text. Use Title tag to choose the appropriate heading level, or None / SPAN when the title is not a document heading.
- Add content inside the item. Supported choices include paragraphs, headings, lists, images, galleries, buttons, icons, Icon Box, Gap, Section, Row, Carousel, Tabs, Modal and nested Accordion blocks. Row continues to contain Columns; Section can contain content directly.
- Select the parent Accordion in List View. Its Panels controls select, reorder, duplicate or remove items. Native List View and block controls remain available.
- Save the draft and preview the public page before publishing.
Choose opening behavior
In the parent Accordion settings, enable One panel at a time to close a sibling when another opens. If several items have Open by default enabled, the first item takes precedence on the public page. With single-panel mode disabled, multiple items can remain open. All panels can be closed in either mode.
Show content in editor and Hide content in editor only change the editing view. They do not change Open by default, and selecting nested content opens its panel for editing. The editor does not run the public collapse animation.
Nested accordions have independent opening rules. Opening an inner panel does not close its outer panel or affect another accordion elsewhere on the page.
Match the theme
- Parent Style offers Dark text and Light text. Item Heading color and Icons color use the theme palette and take precedence over the inherited style; clear a palette selection to inherit.
- The open/closed icons come from the theme's brand settings. Their SVG is saved with each item. After changing those settings, select Refresh theme icons on existing items and save the page to update their snapshots.
- Use parent Visibility and CSS classes for device visibility and existing theme helpers. Each item also has CSS classes. These controls do not create a new stylesheet.
- An optional parent Accessible name labels the accordion region. Use a short description when several accordions need to be distinguished.
Link directly to a panel
Under the item's Panel settings, use Panel ID, for example delivery-details. Link to #delivery-details on the same page or append that fragment to the page URL. The public page opens the target panel and its enclosing accordion panels.
Keep IDs unique. Start with a letter or underscore and use only letters, numbers, hyphens and underscores, without #. Duplicating an item or an entire Accordion generates new conflicting panel IDs. An item's optional native HTML anchor identifies its outer wrapper; Panel ID identifies the expandable body and is the recommended link target.
Convert a Legacy accordion
Place one complete [web_accordion]…[/web_accordion] container in a native Shortcode block, then choose Review panel conversion in its floating toolbar. Review the report and confirm Convert selected container only when it has no blocking warning. The action does not save or publish; Undo restores the original source.
Supported conversion retains the group ID, helper classes, style, one-at-a-time setting, panel title/subtitle/tag, numeric heading/icon palette slots, explicit opening state, optional item wrapper ID and canonical #accordion-… links. It captures the currently configured theme icons, as ordinary static Accordion items do. Panel bodies remain unchanged inside nested Shortcode blocks; unrelated Legacy modules are not converted.
Unknown attributes, missing or duplicate IDs, rich titles, nested panel families, content outside panels and original vc_tta_* structures require manual review. See the Tabs conversion guide for the shared limits, generated-control differences and publishing checks. Always compare paragraph spacing and custom selectors in the full page preview.
Verify the result
- Save and reopen the editor. Confirm the titles, order, content and default-open choices remain intact.
- Preview mobile, both tablet sizes, desktop and Very Large. Check long titles, palette contrast and nested media.
- On the public page, use Tab to focus a heading and Enter or Space to toggle it. Up/Down moves between the current accordion's headings; Home/End moves to its first/last heading.
- Check single-panel and multiple-panel behavior, then open a direct panel link in a fresh page load.
- If a gallery or carousel is inside a panel, open it and confirm its images and navigation fit the available area.
The Accordion and Accordion item blocks save their HTML statically. Their existing theme scripts and conditional stylesheet are discovered from the page content, including when the legacy Page Builder interface is disabled. A nested dynamic Image or Gallery still resolves its own current media independently.
Troubleshooting
- An item looks different from the parent style: check its explicit heading and icon palette selections.
- Updated brand icons are not visible: refresh the item's theme icons and save; changing the global icons does not rewrite already saved static HTML.
- A panel link opens the wrong content: check for a manually reused ID and update the link to the intended item's Panel ID.
- Several panels are visible in the editor despite single-panel mode: the editing view intentionally lets you reach content independently of the public opening rules.