Expand Macro for Confluence: Collapsible Sections Compared (Native vs Styled)
Long pages die from scroll fatigue. Onboarding checklists, troubleshooting trees, API reference details, legal disclaimers — content that only some readers need some of the time is the canonical use case for collapsible sections. Confluence ships a native expand macro for exactly this, and for many pages it's enough.
This guide covers how the native expand works, where teams typically outgrow it, and what a styled accordion macro adds — so you can pick per page, not per vendor.
The native expand macro: how it works
The built-in macro is one slash command away:
- Edit a page, type
/expand - Enter a title — this becomes the clickable toggle text
- Put any content inside: text, tables, images, even other macros
- Publish — viewers click the title to expand or collapse
What it does well:
- Zero setup — works in every Confluence Cloud instance
- Nested content support — anything you can put on a page can go inside
- Predictable, accessible toggle behavior
- Indexes normally in Confluence search
Where teams outgrow it:
- One section per macro. A FAQ with twelve questions means twelve separate macros to create, align, and reorder — each with its own styling drift.
- No accordion mode. All native expands can be open simultaneously; there's no "close others when one opens" behavior.
- Plain styling. The title renders as plain text — no accent color, no icon, no visual hierarchy between sections.
- Collapsed-by-default exports. PDF export of a page full of collapsed expands exports the hidden content in an inconsistent way, which bites print/compliance workflows.
When you need an accordion: the styled Expand macro
When a page has repeated collapsible sections — FAQs, multi-step guides, release notes grouped by version — what you actually want is one macro holding many sections, with consistent styling and accordion behavior. That's the shape of the Expand macro in Content Formatting Macros & Page Builder for Confluence:
- Multiple sections in one macro — add as many as you need, drag to reorder, rich text in each
- True accordion mode — "Allow Multiple Open" off means opening one section closes the others
- Per-section control — title, per-section emoji or character icon, and an "Initially Open" toggle per section (useful for exports: print the sections that matter)
- Five design styles — Simple, Bordered, Shadowed, Gradient, or Minimal, with an accent color picker and content padding control
- Animation — smooth expand/collapse (100–1000ms) instead of an instant jump
The mental model: native expand is a single toggle; a styled accordion is a content structure. Pages with 2–3 toggles rarely need more than native. Pages with 8+ sections benefit from treating the set as one editable unit.
Which should you use, per page type
| Page type | Recommendation |
|---|---|
| Hiding one long table or code sample | Native expand — nothing to gain from more structure |
| FAQ with many Q&As | Styled accordion (or a dedicated FAQ macro) |
| Troubleshooting decision tree | Styled accordion with "one open at a time" so readers follow one path |
| Meeting notes with optional detail | Native expand |
| Release notes grouped by version | Styled accordion — drag-reorder as versions change |
| Onboarding checklist | Styled accordion with icons per phase |
One mechanism, many names
Teams arrive at this page searching for "collapse text", "click to expand", "expandable section", or a "toggle list" — in Confluence they are all the same primitive:
| What you searched | What Confluence calls it |
|---|---|
| Collapse text / hide text behind a click | Expand macro (collapsed by default) |
| Click to expand a section | The expand macro's title bar toggle |
| Expandable / collapsible section | An expand macro holding that section |
| Toggle list, accordion, drop-down list | A stack of expand macros — or one styled accordion macro |
| Spoiler / details tag | Expand macro with a short title |
The native /expand macro covers all of these with plain styling; the styled Expand macro in Content Formatting Macros & Page Builder covers them with icons, accent colors, and accordion behavior.
Common questions from teams
"Does collapsed content hurt SEO?" Content inside collapsible sections is indexed by Google and by Confluence search — collapsing is a presentation choice, not a content hiding mechanism. (That said, critical keywords your page should rank for belong in the open parts of the page, not only inside toggles.)
"Can I nest expand inside expand?" Yes, in both the native macro and the styled accordion's rich-text sections. Nested accordions two levels deep are usually a sign the content wants to be separate pages, though.
"How does this interact with page exports?" Native: collapsed sections may export inconsistently depending on export path. Styled accordion: the "Initially Open" toggle decides, which gives you deterministic print output.
Related reading
- How to build FAQ sections in Confluence — the FAQ-shaped cousin of the accordion
- Confluence block quotes, three ways — another formatting primitive compared
- Confluence pagination: pages and tables — collapsing vs splitting long content across a page series
- Content Formatting Macros & Page Builder — the full macro suite, 23 macros