Collapsible

Patterns

Advanced Filters Block

When to use:

• One secondary form block should stay hidden until needed.

Composition notes:

• Keep the trigger explicit about what becomes available after expansion.
• Treat hidden form errors carefully if the section can be collapsed.

Trade-offs:

• Keeps the main form compact.
• Can hide complexity or validation too effectively if labels are weak.

import { useState } from 'react';
import {
  Button,
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  Label,
  Text,
  TextField,
  TextFieldInput,
} from '@vega-ui/react';

Inline Help Details

When to use:

• One secondary explanation block should stay close to the current content.

Composition notes:

• Keep the hidden content short enough that the trigger still feels like an inline disclosure.
• Prefer Collapsible over Popover when the explanation should stay in document flow.

Trade-offs:

• Preserves reading flow and layout continuity.
• Weaker fit for richly interactive or task-heavy content.

import { Button, Collapsible, CollapsibleContent, CollapsibleTrigger, Text } from '@vega-ui/react';

const lines = [
  { label: 'Team plan · 8 seats × $12', amount: '$96.00' },
  { label: 'Extra storage · 200 GB', amount: '$20.00' },
  { label: 'Annual discount −10%', amount: '−$11.60' },
  { label: 'VAT 19%', amount: '$19.84' },
];

export default function PriceBreakdown() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%', maxWidth: 360 }}>

Secondary Details In Overlays

When to use:

• A drawer or dialog contains one optional detail block that should stay hidden by default.

Composition notes:

• Keep the collapsible content clearly secondary to the main task.
• Test dynamic height with realistic overlay content.

Trade-offs:

• Adds progressive disclosure without introducing another overlay.
• Can make dense panels harder to scan if overused.

import type { CSSProperties } from 'react';
import {
  Button,
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,

Comparison

Quick Decision Rule

Use Collapsible when one standalone expandable section is enough.

Collapsible vs Accordion

Use Collapsible when:

• the feature needs one disclosure block
• grouped state coordination across sections is unnecessary

Use Accordion when:

• several related sections should share one open-state model

Main trade-off: Collapsible stays lighter and simpler, while Accordion gives you coordinated grouped disclosure behavior.

Collapsible vs Popover

Use Collapsible when:

• content should stay inline in the page flow

Use Popover when:

• content should float next to a trigger

Main trade-off: Collapsible preserves layout continuity, while Popover gives stronger local separation.

Choose This Component When

• One expandable section is enough.
• The content should stay inline.
• A simple trigger-to-content disclosure model is all the feature needs.

Do Not Choose This Component When

• Several sections should coordinate.
• The content should behave like a floating overlay.
• The feature needs modal or grouped navigation behavior.

Troubleshooting

Open State And Hidden State Feel Out Of Sync

Symptom

Parent logic observes open, but the content is still visually transitioning or already hidden.

Likely Cause

The feature treats onChangeOpen and onChangeHidden as the same lifecycle signal.

How To Verify

• Log both callbacks during open and close.
• Compare the visual state with the callback timing.

Fix

• Use onChangeOpen for state ownership.
• Use onChangeHidden only when layout or measurement depends on actual visibility.

Custom Trigger Stops Behaving Like A Trigger

Symptom

The disclosure renders, but keyboard behavior or semantics become unclear after custom composition.

Likely Cause

asChild was used with an element that does not preserve trigger-like behavior.

How To Verify

• Inspect the rendered trigger element.
• Test click and keyboard behavior, not just visual rendering.

Fix

• Use a semantically appropriate child with asChild.
• Keep the trigger clearly interactive and keyboard reachable.

Dynamic Content Height Clips Or Jumps

Symptom

Expanded content clips, jumps, or animates strangely as inner content changes.

Likely Cause

The section was only tested with short static content and not with the real dynamic layout.

How To Verify

• Expand the section with realistic asynchronous or variable-height content.
• Check the transition during content growth and collapse.

Fix

• Test with representative content.
• Keep height-transition assumptions conservative when the content is highly dynamic.