> ## Documentation Index
> Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Progressive disclosure with accordions

> Use accordions to hide optional details until readers need them.

export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
  const [selected, setSelected] = React.useState(null);
  const [checked, setChecked] = React.useState(false);
  const quizId = React.useId();
  const isCorrect = checked && answers[selected]?.correct;
  const reset = () => {
    setSelected(null);
    setChecked(false);
  };
  return <div className={"quiz-container" + (checked ? " quiz-checked" : "")}>
      <Badge color="green">Quiz</Badge>
      <p className="quiz-question" id={quizId + "-question"}>{question}</p>
      <div className="quiz-options" role="radiogroup" aria-labelledby={quizId + "-question"} aria-disabled={checked}>
        {answers.map((answer, i) => <label key={i} className={["quiz-option", !checked && selected === i ? "quiz-option-selected" : "", checked && answer.correct ? "quiz-option-correct" : "", checked && selected === i && !answer.correct ? "quiz-option-incorrect" : ""].filter(Boolean).join(" ")}>
            <input type="radio" name={"quiz-" + quizId} checked={selected === i} onChange={() => !checked && setSelected(i)} disabled={checked} />
            <span className="quiz-radio" />
            <span className="quiz-option-label">{answer.text}</span>
          </label>)}
      </div>
      {checked && <div className={"quiz-feedback " + (isCorrect ? "quiz-feedback-correct" : "quiz-feedback-incorrect")} role="status" aria-live="polite" aria-atomic="true">
          <span className="quiz-feedback-icon">{isCorrect ? "✓" : "✗"}</span>
          {isCorrect ? correctFeedback : incorrectFeedback}
        </div>}
      <div className="quiz-actions">
        {!checked ? <button className="quiz-btn quiz-btn-check" type="button" onClick={() => selected !== null && setChecked(true)} disabled={selected === null}>
            Check answer
          </button> : <button className="quiz-btn quiz-btn-reset" type="button" onClick={reset}>
            Try again
          </button>}
      </div>
    </div>;
};

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

```mdx Example of an accordion for a troubleshooting step theme={null}
<Accordion title="Fix a connection timeout">
  Confirm that your firewall allows outbound traffic on port 443, then retry the request.
</Accordion>
```

<Accordion title="Fix a connection timeout">
  Confirm that your firewall allows outbound traffic on port 443, then retry the request.
</Accordion>

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.

```mdx Example of a required action inside an accordion - don't do this theme={null}
<Step title="Add the environment variable">
  Add `API_KEY` to your `.env` file.

  <Accordion title="Additional details">
    Restart your development server to load the new value.
  </Accordion>
</Step>
```

<Step title="Add the environment variable">
  Add `API_KEY` to your `.env` file.

  <Accordion title="Additional details">
    Restart your development server to load the new value.
  </Accordion>
</Step>

Keep the restart instruction visible in the step. Save the accordion for information that only some readers need.

```mdx Example of a better use of an accordion theme={null}
<Step title="Add the environment variable">
  1. Add `API_KEY` to your `.env` file.
  2. Restart your development server.

  <Accordion title="The new value isn't loading">
    Confirm that the file is named `.env` and is in the project root.
  </Accordion>
</Step>
```

<Step title="Add the environment variable">
  1. Add `API_KEY` to your `.env` file.
  2. Restart your development server.

  <Accordion title="The new value isn't loading">
    Confirm that the file is named `.env` and is in the project root.
  </Accordion>
</Step>

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.

```mdx theme={null}
<AccordionGroup>
  <Accordion title="The CLI command isn't available">
    Restart your terminal or run the command with `npx mint`.
  </Accordion>
  <Accordion title="Port 3000 is already in use">
    Run `mint dev --port 3333` to choose another port.
  </Accordion>
</AccordionGroup>
```

<AccordionGroup>
  <Accordion title="The CLI command isn't available">
    Restart your terminal or run the command with `npx mint`.
  </Accordion>

  <Accordion title="Port 3000 is already in use">
    Run `mint dev --port 3333` to choose another port.
  </Accordion>
</AccordionGroup>

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.

<Quiz
  question="A deployment guide includes a required command, an optional proxy configuration, and a warning that deploying a new version replaces the current production version. Which content belongs in an accordion?"
  answers={[
{ text: "The proxy configuration only", correct: true },
{ text: "The command and proxy configuration", correct: false },
{ text: "The warning and proxy configuration", correct: false },
{ text: "All three, because readers can open the details they need", correct: false },
]}
  correctFeedback="Right. Most readers can skip the proxy configuration, so it can stay nearby without interrupting the main path. Keep the required command and production warning visible."
  incorrectFeedback="Only the proxy configuration is optional. The command is part of the procedure, and the production warning needs to be visible before anyone deploys."
/>

<Check>
  Next up: [Code block essentials](/courses/components/code-blocks) — Make examples easier to understand and use.
</Check>