Skip to main content
Say you’re writing a setup guide with troubleshooting steps for three uncommon errors. Putting every fix in the main page content makes the guide longer and people have to read information they might not need. Moving the troubleshooting steps to another page makes readers search for help if they need it. This is a good scenario for using accordions, which only reveal content when readers click on them. The troubleshooting information stays on the page, but readers control when they read it. This approach is called progressive disclosure. Show the essentials first and let readers reveal more specific details as needed. 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.

​
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.

​
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.
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.
Next up: Code block essentials — Make examples easier to understand and use.