# Expandable

The **Expandable** widget is a versatile UI component that allows you to show or hide content dynamically. It consists of a header that remains always visible and collapsible content that can be revealed or hidden with a tap. This widget is particularly useful for creating accordions, FAQ sections, collapsible forms, and any interface where space conservation is important while still providing access to detailed information on demand.

{% embed url="<https://youtu.be/PktfH9FuYuA?si=95cZnZQyuLCEOHtK>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=PktfH9FuYuA>

Expandable widgets help reduce visual clutter by allowing users to access information only when they need it, creating cleaner, more organized interfaces especially on mobile devices or complex forms.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-9c15725895ee9400ea8b9eebbbdec3e9257df0f1%2Fexpandable.png?alt=media" alt="A hero image illustrating an Expandable widget with collapsible content."><figcaption><p>An interactive widget for showing and hiding content dynamically with smooth animations.</p></figcaption></figure>

{% hint style="info" %}
Our Expandable widget follows Flutter's `ExpansionPanel` and `ExpansionTile` patterns, providing smooth animations, flexible content configuration, and comprehensive interaction options.
{% endhint %}

### Core Concepts

#### 1. Three Required Children Slots

The Expandable widget requires **three separate child widgets** to function properly:

* **`header`**: The always-visible part that users tap to toggle expansion.
* **`collapsedView`**: The content shown when the widget is in its collapsed state.
* **`expandedView`**: The content shown when the widget is in its expanded state.

All three children are required. The widget automatically handles the transition between collapsed and expanded views based on user interaction.

#### 2. State Management: Collapsed vs. Expanded

The Expandable widget maintains an internal state that determines which view is currently visible:

* **Collapsed State**: Shows the header and collapsedView content.
* **Expanded State**: Shows the header and expandedView content.

You can control the initial state using the `Initially Expanded` property, and users can toggle between states by tapping (depending on your tap behavior configuration). You can also bind `Initially Expanded` to expressions or variables to dynamically control the expansion state based on app logic.

#### 3. Tap Behavior Flexibility

Unlike simple toggles, Expandable provides granular control over tap interactions:

* **Tap Header to Toggle**: Most common pattern—tapping the header switches states.
* **Tap Body to Expand**: Tapping the collapsed content can expand it.
* **Tap Body to Collapse**: Tapping the expanded content can collapse it.

These options can be enabled independently, giving you complete control over the interaction model.

#### 4. Visual Feedback with Icons & Animations

Expandable provides built-in support for:

* **Expand/Collapse Icons**: Automatically swap icons based on state.
* **Icon Rotation**: Smoothly rotate icons during transitions (e.g., chevron pointing down → up).
* **Animation Duration**: Control how fast the expand/collapse animation plays.
* **InkWell Effect**: Add Material Design ripple effects to interactions.

***

### Children Slots

The Expandable widget has three **required** children slots:

<table><thead><tr><th width="180">Slot</th><th>Description</th></tr></thead><tbody><tr><td><code>header</code></td><td><strong>Required.</strong> The always-visible part of the widget, typically containing a title or label. This is what users see and tap to toggle expansion.</td></tr><tr><td><code>collapsedView</code></td><td><strong>Required.</strong> The content displayed when the widget is in its collapsed state. Often contains a brief summary, preview, or placeholder.</td></tr><tr><td><code>expandedView</code></td><td><strong>Required.</strong> The content displayed when the widget is in its expanded state. Contains the full detailed information or interactive elements.</td></tr></tbody></table>

***

### Properties

#### Active View Property

<table><thead><tr><th width="200">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Active View</code></td><td><strong>Dashboard Preview Only.</strong> Controls whether the widget appears in the <code>Collapsed</code> or <code>Expanded</code> state in the builder dashboard. This is purely for design preview purposes and does not affect the runtime behavior of the widget.</td></tr><tr><td><code>Initially Expanded</code></td><td>If <code>true</code>, the widget will be in the expanded state by default when the page first loads in the actual app. Default is <code>false</code> (collapsed). This is the property that controls the real initial state.</td></tr></tbody></table>

#### Tap Behavior Properties

These properties control how users can interact with the widget:

<table><thead><tr><th width="220">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Tap Header to Toggle</code></td><td>If <code>true</code>, tapping anywhere on the header will toggle between collapsed and expanded states. This is the most common interaction pattern.</td></tr><tr><td><code>Tap Body to Expand</code></td><td>If <code>true</code>, tapping on the collapsed content will expand the widget. Useful when you want the collapsed content to be interactive.</td></tr><tr><td><code>Tap Body to Collapse</code></td><td>If <code>true</code>, tapping on the expanded content will collapse the widget. Useful for "dismiss" behavior.</td></tr></tbody></table>

{% hint style="info" %}
**Tip:** You can enable multiple tap behaviors simultaneously. For example, enable both "Tap Header to Toggle" and "Tap Body to Collapse" to allow users to collapse from either location.
{% endhint %}

#### Alignment Properties

Control how content is positioned within each slot:

<table><thead><tr><th width="200">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Alignment</code></td><td>The alignment of the entire expandable widget within its parent container (e.g., left, center, right).</td></tr><tr><td><code>Header Alignment</code></td><td>The alignment of content within the header slot. Controls how child widgets are positioned inside the header.</td></tr><tr><td><code>Body Alignment</code></td><td>The alignment of content within the collapsed and expanded view slots.</td></tr></tbody></table>

#### Icon Properties

The Expandable widget has built-in support for state-indicating icons:

<table><thead><tr><th width="220">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Has Icon</code></td><td>If <code>true</code>, an icon will be displayed in the header to indicate the expand/collapse state.</td></tr><tr><td><code>Icon Placement</code></td><td>Where to position the icon within the header: <code>Left</code> or <code>Right</code>.</td></tr><tr><td><code>Collapsed Icon</code></td><td>The icon to display when the widget is in the collapsed state (e.g., chevron_down, add, arrow_forward).</td></tr><tr><td><code>Expanded Icon</code></td><td>The icon to display when the widget is in the expanded state (e.g., chevron_up, remove, arrow_drop_down).</td></tr><tr><td><code>Icon Size</code></td><td>The size of the icon in pixels. Default is typically 24px.</td></tr><tr><td><code>Icon Color</code></td><td>The color of the icon. Can be set from your design system colors or as a custom hex value.</td></tr><tr><td><code>Icon Padding</code></td><td>The padding around the icon to create spacing between the icon and other header content.</td></tr><tr><td><code>Icon Rotation Angle</code></td><td>The angle (in degrees) to rotate the icon when transitioning to the expanded state. Creates smooth rotation animations (e.g., 180° to flip a chevron).</td></tr></tbody></table>

{% hint style="success" %}
**Icon Best Practice:** Use consistent icon pairs across your app:

* `chevron_right` / `expand_more` for horizontal/vertical expansion
* `add` / `remove` for accordion-style interfaces
* `arrow_forward` / `arrow_drop_down` for dropdown-like behavior
  {% endhint %}

#### Style & Animation Properties

<table><thead><tr><th width="220">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Animation Duration</code></td><td>The duration of the expand and collapse animation in milliseconds. Default is typically 300ms. Lower values create snappier transitions, higher values create smoother, more deliberate animations.</td></tr><tr><td><code>Use InkWell Effect</code></td><td>If <code>true</code>, a Material Design ripple effect will be shown when the user taps the widget. Provides tactile feedback.</td></tr><tr><td><code>InkWell Border Radius</code></td><td>The corner radius for the ripple effect when InkWell is enabled. Should typically match your container's border radius for visual consistency.</td></tr></tbody></table>

***

### Use Cases

Expandable is ideal for:

* **FAQ Sections**: Display questions as headers with answers that expand on tap.
* **Accordion Menus**: Create collapsible navigation or category lists.
* **Settings Panels**: Hide advanced options until users need them.
* **Product Details**: Show basic info by default, expand for specifications.
* **Forms with Sections**: Organize long forms into collapsible sections.
* **Filter Panels**: Show/hide filter options in e-commerce or search interfaces.
* **Reading Lists**: Display article titles with expandable summaries.
* **Terms & Conditions**: Show abbreviated text with full text expansion.
* **Educational Content**: Display lesson titles with expandable content.
* **User Profiles**: Collapse sections like "About", "Skills", "Experience".

{% hint style="success" %}
**User Experience Tip:** Always provide clear visual indicators (like icons or arrows) that show whether content is expanded or collapsed. This helps users understand the widget's interactive nature.
{% endhint %}

***

### Best Practices

#### Design Guidelines

**Visual Consistency:**

* Use consistent header styling across all expandable widgets in your app
* Maintain the same icon style (filled vs outlined) throughout
* Keep animation durations uniform for predictable UX

**Content Organization:**

* Place most important information in the header
* Use collapsedView for teasers or summaries
* Reserve expandedView for detailed content or actions

**Accessibility:**

* Ensure sufficient tap target size for headers (minimum 44x44 points)
* Use clear, descriptive header text
* Provide adequate color contrast for text and icons

#### Performance Considerations

**Lazy Loading:**

* For heavy content in expandedView, consider lazy loading images or data
* Don't load all expanded content upfront if you have many expandables

**Animation Optimization:**

* Keep animation durations under 500ms for responsive feel
* Avoid animating heavy widgets; use lightweight containers

**List Performance:**

* When using multiple Expandables in a ListView, ensure only one is expanded at a time
* Use state management to track which item is expanded

#### Common Patterns

**Progressive Disclosure:** Use expandables in multi-step forms to reveal sections.

**Search & Expand:** Combine search functionality with expandables:

```
Search results → Each result is an Expandable
- Header shows title and summary
- CollapsedView shows brief preview
- ExpandedView shows full content
```

***

### Default Properties

The Expandable widget supports all [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").