Expandable

A collapsible section for showing and hiding additional content

The Expandable component provides a simple way to show and hide content with customizable toggle text. It’s commonly used for displaying optional details, child attributes, or nested information in API documentation.

Basic Usage

<Expandable title="details">
  <div className="py-4">
    <p>This is the expandable content that appears when opened.</p>
  </div>
</Expandable>

Props

title · string · default: "child attributes"

The text displayed in the toggle button after “Show” or “Hide”.

defaultOpen · boolean · default: false

Whether the expandable should be open by default.

openedText · string · default: "Hide"

The text displayed when the expandable is open (before the title).

closedText · string · default: "Show"

The text displayed when the expandable is closed (before the title).

lazy · boolean · default: false

When true, children are not rendered until the expandable is first opened. Useful for performance optimization with heavy content.

className · string

Additional CSS classes to apply to the expandable container.

children · ReactNode

The content to display inside the expandable when opened.

onChange · (open: boolean) => void

Callback fired when the expandable state changes. Receives the new open state.

onOpen · () => void

Callback fired when the expandable is opened.

onClose · () => void

Callback fired when the expandable is closed.

onMount · () => void

Callback fired when the expandable component mounts.

uniqueParamId · string

Unique identifier for session storage persistence. When provided, the expandable state is saved and restored across page reloads.

anchor · string

Anchor identifier for deep linking. When the URL contains this anchor, the expandable automatically opens.

hasScrolledToAnchorRef · RefObject<boolean>

Ref object to track if scrolling to anchor has occurred. Used internally for anchor-based navigation.

Examples

Default (Closed)

<Expandable title="details">
  <div className="py-4">
    <p>This expandable starts in the closed state.</p>
  </div>
</Expandable>

Default Open

<Expandable title="details" defaultOpen={true}>
  <div className="py-4">
    <p>This expandable starts in the open state.</p>
  </div>
</Expandable>

Custom Title

<Expandable title="advanced options">
  <div className="py-4">
    <p>The title prop customizes what appears after "Show" or "Hide".</p>
  </div>
</Expandable>

Custom Toggle Text

<Expandable 
  title="section" 
  openedText="Collapse" 
  closedText="Expand"
>
  <div className="py-4">
    <p>
      Custom toggle text: "Expand section" when closed, 
      "Collapse section" when open.
    </p>
  </div>
</Expandable>

Internationalization

<Expandable 
  title="atributos secundarios" 
  openedText="Ocultar" 
  closedText="Mostrar"
>
  <div className="py-4">
    <p>Este es el contenido del componente expandible en español.</p>
  </div>
</Expandable>

With Callbacks

<Expandable
  title="interactive content"
  onChange={(open) => console.log("onChange:", open)}
  onOpen={() => console.log("onOpen")}
  onClose={() => console.log("onClose")}
  onMount={() => console.log("onMount")}
>
  <div className="py-4">
    <p>
      Toggle this expandable and check the browser console 
      to see the callbacks firing.
    </p>
  </div>
</Expandable>

Lazy Loading

<Expandable title="lazy content" lazy={true}>
  <div className="py-4">
    <p>
      With lazy=true, children are not rendered until the 
      expandable is first opened.
    </p>
    <ExpensiveComponent />
  </div>
</Expandable>

Use lazy={true} for expandables containing heavy content like large data tables, charts, or complex components to improve initial page load performance.

Custom Styling

<Expandable 
  title="styled content" 
  className="bg-blue-50 dark:bg-blue-950"
>
  <div className="py-4">
    <p>Custom className applied to the root element for styling.</p>
  </div>
</Expandable>

API Documentation Use Case

<Expandable title="response fields" defaultOpen={true}>
  <div className="space-y-3 py-4">
    <div>
      <code className="text-pink-600 dark:text-pink-400">id</code>
      <span className="ml-2 text-sm text-stone-500">string</span>
      <p className="mt-1 text-sm text-stone-600 dark:text-stone-400">
        Unique identifier for the resource.
      </p>
    </div>
    <div>
      <code className="text-pink-600 dark:text-pink-400">name</code>
      <span className="ml-2 text-sm text-stone-500">string</span>
      <p className="mt-1 text-sm text-stone-600 dark:text-stone-400">
        Display name of the resource.
      </p>
    </div>
    <div>
      <code className="text-pink-600 dark:text-pink-400">createdAt</code>
      <span className="ml-2 text-sm text-stone-500">datetime</span>
      <p className="mt-1 text-sm text-stone-600 dark:text-stone-400">
        Timestamp when the resource was created.
      </p>
    </div>
  </div>
</Expandable>

With Session Storage Persistence

<Expandable title="persistent state" uniqueParamId="my-expandable-id">
  <div className="py-4">
    <p>
      This expandable's state persists across page reloads 
      using session storage.
    </p>
  </div>
</Expandable>

When using uniqueParamId, ensure each expandable has a unique ID to avoid state conflicts.

Nested Expandables

<Expandable title="parent section" defaultOpen={true}>
  <div className="py-4">
    <p>This is the parent expandable content.</p>
    
    <Expandable title="nested section 1">
      <div className="py-4">
        <p>First nested expandable content.</p>
      </div>
    </Expandable>
    
    <Expandable title="nested section 2">
      <div className="py-4">
        <p>Second nested expandable content.</p>
      </div>
    </Expandable>
  </div>
</Expandable>

Styling

The Expandable component automatically adapts to light and dark themes with a subtle border and hover effects:

• Light mode: Light gray border with darker hover state
• Dark mode: White border with lighter hover state

The toggle button includes:

• A chevron icon that rotates 90° when open
• Hover effects for better interactivity
• Focus states for keyboard navigation

Behavior

Toggle Interaction

The expandable can be toggled by:

• Clicking anywhere on the summary bar
• Keyboard navigation (Enter/Space on the summary element)

Animation

The expand/collapse animation is handled natively by the browser using the <details> element, providing smooth transitions across all browsers.

Accessibility

The Expandable component includes built-in accessibility features:

• Uses native HTML <details> and <summary> elements
• Proper ARIA attributes (aria-controls, aria-expanded)
• Keyboard navigation support
• Focus indicators for keyboard users
• Unique IDs for content regions
• Semantic HTML structure for screen readers

The expandable automatically generates unique IDs for ARIA attributes based on the title and React’s useId hook.

Common Use Cases

API Response Properties

<ParamField path="user" type="object">
  User information
  
  <Expandable title="properties">
    <div className="py-4">
      <ParamField path="id" type="string">User ID</ParamField>
      <ParamField path="name" type="string">User name</ParamField>
      <ParamField path="email" type="string">User email</ParamField>
    </div>
  </Expandable>
</ParamField>

Optional Configuration

<Expandable title="advanced configuration">
  <div className="py-4">
    <h4>Advanced Options</h4>
    <ul>
      <li><strong>timeout</strong>: Request timeout in milliseconds</li>
      <li><strong>retries</strong>: Number of retry attempts</li>
      <li><strong>cache</strong>: Enable response caching</li>
    </ul>
  </div>
</Expandable>

Technical Details

<Expandable title="technical specifications">
  <div className="py-4">
    <table>
      <tr>
        <td>Protocol</td>
        <td>HTTPS</td>
      </tr>
      <tr>
        <td>Authentication</td>
        <td>Bearer Token</td>
      </tr>
      <tr>
        <td>Rate Limit</td>
        <td>1000 requests/hour</td>
      </tr>
    </table>
  </div>
</Expandable>