Accordion

Patterns

FAQ Group

When to use:

• Several short answers belong to one help or support block.

Composition notes:

• Keep each trigger specific enough that users can scan the list without opening every item.
• Use one root so all sections share the same disclosure model.

Trade-offs:

• Good for scannable grouped help.
• Weak fit for highly interactive form flows.

import {
  Accordion,
  AccordionContent,
  AccordionHeader,
  AccordionIcon,
  AccordionItem,
  AccordionTrigger,
  Separator,
  Text,
} from '@vega-ui/react';

const questions = [

Settings Sections

When to use:

• A larger settings form should be broken into manageable expandable blocks.

Composition notes:

• Keep the currently relevant section open by default.
• Make sure collapsed sections still show enough context in their trigger labels.

Trade-offs:

• Helps compress long forms.
• Can hide important validation if section state is not handled carefully.

import { FormEvent, useState } from 'react';
import {
  Accordion,
  AccordionContent,
  AccordionHeader,
  AccordionIcon,
  AccordionItem,
  AccordionTrigger,
  Button,
  Label,
  Separator,
  TextField,

Inline Help Inside Overlays

When to use:

• A drawer or dialog needs expandable secondary guidance without leaving the current task.

Composition notes:

• Keep the accordion secondary to the main task.
• Avoid letting every section become a full-page replacement inside the overlay.

Trade-offs:

• Preserves local context and keeps help close to the task.
• Can create a visually dense panel if too many sections are expanded.

import type { CSSProperties } from 'react';
import {
  Accordion,
  AccordionContent,
  AccordionHeader,
  AccordionIcon,
  AccordionItem,
  AccordionTrigger,
  Button,
  Drawer,
  DrawerClose,
  DrawerContent,

Comparison

Quick Decision Rule

Use Accordion when several related sections should share one disclosure model.

Accordion vs Collapsible

Use Accordion when:

• multiple sections belong to one grouped disclosure pattern
• open-state coordination across sections matters

Use Collapsible when:

• one standalone disclosure block is enough
• the feature does not need grouped item semantics

Main trade-off: Accordion gives you coordinated grouped behavior, while Collapsible stays lighter for one-off sections.

Accordion vs Drawer

Use Accordion when:

• the content should stay inline in the current layout

Use Drawer when:

• the content deserves a separate overlay panel

Main trade-off: Accordion preserves inline context, while Drawer provides stronger separation and more space.

Choose This Component When

• Several expandable sections belong to one grouped UI.
• Users benefit from opening one or several related sections inline.
• The layout should stay on the page instead of moving into an overlay.

Do Not Choose This Component When

• You only need one expandable section.
• The content needs modal or overlay separation.
• The open-state model across sections is irrelevant.

Troubleshooting

Only The Icon Feels Clickable

Symptom

Users try to click the row, but only the icon appears to react like the trigger.

Likely Cause

The trigger composition was restyled in a way that visually isolates the icon from the full-width button.

How To Verify

• Hover and click across the full trigger width.
• Inspect whether custom children or wrappers changed the button layout.

Fix

• Keep AccordionTrigger as the main interaction surface.
• Treat AccordionIcon as decoration inside that trigger.

Open State Does Not Match Parent Logic

Symptom

Sections open and close, but the parent feature state falls out of sync.

Likely Cause

The root is being treated like an uncontrolled accordion while the parent expects controlled behavior.

How To Verify

• Check whether opened and onChangeOpened are wired together.
• Compare the visible state with parent data after several toggles.

Fix

• Use opened and onChangeOpened together for parent-owned state.
• Keep defaultOpened for uncontrolled flows only.

Form Errors Disappear Inside Collapsed Sections

Symptom

Validation exists, but users do not notice it because the relevant section is collapsed.

Likely Cause

Accordion state and form-error visibility were not designed together.

How To Verify

• Trigger a real validation error inside a collapsed section.
• Check whether the outer UI signals which section needs attention.

Fix

• Open the invalid section automatically or show a visible section-level error hint.
• Do not rely on hidden inner error copy as the only signal.