# Expandables
Use expandables for optional field details, nested properties, and advanced notes.
Source: /docs/components/expandables
Last modified: 2026-06-20
Expandables keep secondary information nearby without making the first read heavy.

## Basic expandable

Mintlify uses expandables most often inside response fields to reveal nested object properties without making the first read heavy.


- `user` (User Object):

> **properties**
>


- `full_name` (string):
      The full name of the user.


- `is_over_21` (boolean):
      Whether the user is over 21 years old.


```mdx title="expandable-properties.mdx"

- `user` (User Object):

> **properties**
>


- `full_name` (string):
      The full name of the user.


- `is_over_21` (boolean):
      Whether the user is over 21 years old.


```

## Standalone expandable


> **metadata**
>

  Use metadata for implementation-owned values such as source page, campaign, or account ID.


```mdx title="expandable-example.mdx"

> **metadata**
>

  Use metadata for implementation-owned values such as source page, campaign, or account ID.


```

## Open by default

Open an expandable when the nested detail is important but still visually secondary to the surrounding section.


> **customer**
>

  Include `email` when you already know the buyer. Plandalf can use it to prefill checkout and connect purchase records.


```mdx title="default-open-expandable.mdx"

> **customer**
>

  Include `email` when you already know the buyer.


```

## Nested API details

Use expandables inside request or response fields when the first read should show the object name, and the second read should show the nested shape.


### Request body


- `offer` (string; required):
    Offer slug or route key.


- `metadata` (object; optional):
    Implementation-owned metadata for reporting, routing, or fulfillment.


> **metadata**
>

      Common keys include `source`, `campaign`, `account_id`, and `template_id`. Keep values flat unless your backend owns the nested shape.


```mdx title="expandable-field-detail.mdx"

### Request body


- `metadata` (object; optional):
    Implementation-owned metadata.


> **metadata**
>

      Common keys include `source`, `campaign`, `account_id`, and `template_id`.


```

## Properties


- `title` (string):
  The name of the object you are showing.


- `defaultOpen` (boolean; default: false):
  Set to `true` for the expandable to open when the page loads.


## Plandalf extensions


- `label` (string; default: Show properties):
  Closed-state action text.


- `openLabel` (string; default: Hide properties):
  Open-state action text.


- `description` (string):
  Optional supporting text below the title.


- `icon | iconType` (string):
  Optional icon shown before the title.


- `class | className` (string):
  Optional classes for layout adjustments.


## Authoring rules

- Put the primary explanation outside the expandable.
- Use expandables for optional shapes, advanced behavior, and nested API detail.
- Use accordions when the page has several peer sections the reader may open independently.
- Avoid hiding required setup steps inside an expandable.

## Related


  - [Accordions](/docs/components/accordions): Group multiple optional sections.
  - [Response fields](/docs/components/response-fields): Nest response properties.
  - [View](/docs/components/view): Switch larger content blocks.