Skip to main content
A rule to remember: readers should be able to complete the task without opening an accordion. If skipping the content could make the task fail, keep it visible. Say you’re writing a setup guide with fixes for three uncommon errors. Putting every fix in the main content makes everyone read information most of them don’t need. Moving the fixes to another page makes the readers who do need them go looking. Accordions solve this. They only reveal content when readers click on them, so the fixes stay on the page and readers decide when to read them. This approach is called progressive disclosure: show the essentials first and let readers reveal details as needed.

​
What belongs in an accordion

Use accordions for details that help some readers but are safe for everyone else to skip.
  • A fix for a specific error message
  • Customizing settings that don’t affect the standard setup
  • Diagnostic information for investigating an unexpected result
  • Background that explains why a step works without changing what the reader should do
Example of an accordion for a troubleshooting step
Confirm that your firewall allows outbound traffic on port 443, then retry the request.
The title identifies who needs the content. Readers who don’t have a connection timeout can keep moving. Opening an accordion updates the page URL, so you can link straight to it. That’s useful for support: send someone a link to the exact fix instead of the whole page.

​
Keep required steps visible

Prerequisites, required actions, warnings, and expected results should always be visible. Do not hide them within an accordion. Suppose every reader must do a task, like restart the development server after changing an environment variable. Hiding that instruction makes the procedure look shorter, but it also makes it harder to complete since someone may not click into the accordion and see the required task.
Example of a required action inside an accordion - don't do this
1

Add the environment variable

Add API_KEY to your .env file.
Restart your development server to load the new value.
Keep the restart instruction visible in the step. Save the accordion for information that only some readers need.
Example of a better use of an accordion
1

Add the environment variable

  1. Add API_KEY to your .env file.
  2. Restart your development server.
Confirm that the file is named .env and is in the project root.
Don’t use accordions simply to make a long page look shorter. If the hidden sections have separate goals or must be read in order, split the page or use visible sections.

​
Group independent details

Use <AccordionGroup> when several related items can be read independently.
Example of an accordion group
Restart your terminal or run the command with npx mint.
Run mint dev --port 3333 to choose another port.
A reader can open either accordion without reading the other. If one accordion depends on another, the content isn’t independent and should probably be a procedure. Be careful with long accordion groups. A stack of ten vague titles forces readers to open each one just to find out what the page contains. Break up the group, improve the titles, or move substantial topics to their own sections.

​
Choose the component by what readers need

Several components hide or emphasize content, but they solve different problems.
  • Optional detail → accordion
  • A version for the reader’s operating system, framework, or other context → tabs
  • Nested fields in API reference content → expandable
  • Information readers must notice → callout or main content
Choose what components to use based on the decision readers need to make. Don’t use components just for visual design.

​
Give readers a reason to open accordions

Accordion titles must describe what is inside. “More,” “Details,” and “Learn more” force readers to guess. “Fix a 401 response” and “Configure a proxy” make the choice clear. If the title alone isn’t enough, add a description to show a short line of detail under it. Next up: Code block essentials—make examples easier to understand and use.