AccordionDetails - spec
Direct upstream component: MUI AccordionDetails. Parent pattern references: Ant Design Collapse, MUI Accordion, shadcn-ui accordion.
Purpose
AccordionDetails is the body container for the expanded content of one accordion item. It holds text, forms, lists, or supporting controls that are disclosed by AccordionSummary.
Use it when content is secondary until the user chooses to expand the section. Keep critical information visible outside the accordion.
Anatomy
Accordion.Item
├── AccordionSummary expands/collapses the section
└── AccordionDetails revealed body region
├── Body content
├── Inline controls
└── Optional nested layout
| Part |
Required |
Purpose |
| Root |
yes |
Body wrapper linked to the summary through the parent item. |
| Content |
yes |
Any readable or interactive content. |
| Region semantics |
parent-owned |
role="region" and labels usually belong to the collapsible content wrapper, not an inner styling div. |
API
<Accordion.Item value="security">
<Accordion.Summary>보안</Accordion.Summary>
<Accordion.Details>
<p>2단계 인증과 로그인 알림을 관리합니다.</p>
<SecuritySettings />
</Accordion.Details>
</Accordion.Item>
| Prop |
Type |
Default |
Description |
children |
ReactNode |
- |
Body content for the expanded panel. |
classes |
Partial<AccordionDetailsClasses> |
- |
Style override hooks for MUI-style implementations. |
sx |
SxProps<Theme> |
- |
MUI system override. Prefer tokens for shared design-system code. |
API choices made
- Keep
AccordionDetails layout-only. Expansion state, aria-expanded, and keyboard behavior stay on AccordionSummary / parent item.
- Do not add
padding, variant, or scroll props. Use parent accordion variants and tokenized CSS.
- Do not make the details wrapper focusable by default. Focus should move to meaningful content inside.
States
| State |
Trigger |
Visual rule |
| Collapsed |
Parent item closed |
Details content is hidden and not keyboard reachable. |
| Expanding |
Parent item opens |
Body follows parent expand motion; no separate fade unless specified by parent. |
| Expanded |
Parent item open |
Content uses readable spacing and inherits text color. |
| Focus-visible |
Focusable child receives focus |
Child shows visible focus; details wrapper remains neutral. |
| Disabled |
Parent item disabled |
Details remain collapsed unless parent allows disabled expanded display; text is not independently disabled. |
| Loading |
Async content inside |
Use skeleton or progress inside details, not on the wrapper. |
| Error |
Form/list error inside |
Show error near the failing field/section and reflect status in summary if needed. |
Tokens consumed
--color-bg-default
--color-bg-subtle
--color-text-primary
--color-text-secondary
--color-border-default
--color-focus-ring
--space-sm
--space-md
--space-lg
--radius-md
--motion-default
--easing-in-out
Accessibility
- The accordion content wrapper should have
id, role="region" when the panel is substantial, and aria-labelledby pointing to the summary button.
- Do not add a second unlabeled
region inside AccordionDetails.
- Hidden details must not leave form fields, links, or buttons in the tab order.
- If content is short plain text,
role="region" is optional; overusing regions makes screen-reader navigation noisy.
- Keyboard behavior is inherited from the parent accordion:
Tab enters visible focusable content, and Enter / Space toggles the summary.
- Touch target rules apply to controls inside details: at least 44x44 on mobile.
Layout rules
| Rule |
Value |
| Padding |
Match parent size: sm 12px, md 16px, lg 20px equivalent tokens. |
| Text |
Body text uses --color-text-primary; helper copy uses --color-text-secondary. |
| Width |
Fill parent item width. Avoid fixed widths inside details. |
| Scroll |
Prefer page scroll. Only create inner scroll if the panel is inside a constrained modal/drawer. |
| Forms |
Preserve field state across collapse unless product explicitly discards edits. |
Code example
<Accordion type="single" collapsible defaultValue="account">
<Accordion.Item value="account">
<Accordion.Summary>계정 정보</Accordion.Summary>
<Accordion.Details>
<Stack gap="md">
<Text tone="secondary">
이름과 연락처는 본인인증 이후에만 변경할 수 있습니다.
</Text>
<AccountProfileFields />
</Stack>
</Accordion.Details>
</Accordion.Item>
</Accordion>
Edge cases
- Async body data: render a skeleton inside the expanded details. Do not collapse the panel while loading.
- Form state: keep fields mounted or persist their values before unmounting, otherwise collapse can discard edits.
- Very long content: consider splitting into separate accordion items or a dedicated page.
- Nested accordions: avoid by improving information architecture; if unavoidable, nested summaries must have distinct labels.
- Tables inside details: ensure horizontal overflow is keyboard accessible and not clipped by the accordion item.
- High contrast mode: body/background boundaries must remain visible through border or spacing, not color alone.
- Print: print styles should expand important details or provide a clear "collapsed content omitted" rule.
Don't
- Don't make
AccordionDetails itself a button, link, or focus target.
- Don't put critical CTAs only inside details.
- Don't add independent expand/collapse logic inside the details wrapper.
- Don't hide validation errors by collapsing the panel after submit.
References
Cross-reference