M3E Expandable #

A Flutter package providing expressive, Material 3 expandable card lists with dynamically rounded corners inside normal ListViews, Columns, CustomScrollViews (via slivers), and spring-physics reorderable lists (M3EReorderableExpandableList). Features smooth spring-driven expand/collapse animations with expressive M3 styling.

It automatically calculates and draws the corners to fit exactly the Material 3 Expressive spec for adjacent items. It gives extensive customization options including InkSparkle splash ripples, custom border colors, custom elevation, pressed scale micro-interactions, zero-layout-impact focus rings, and highly tunable haptic feedback along with stiffness and damping for animations.

🎮 Interactive Demo #

You can try out the package demo here: m3e_core demo

🚀 Features #

• Dynamic border radius: The first and last items get a larger outer radius while adjoining cards receive a smaller inner radius seamlessly.
• Spring-Physics Reordering: M3EReorderableExpandableList with spring lift-off motion, dynamic placeholder slots, bouncy neighbor displacement, and smooth snap settling.
• Pressed Scale Micro-Interactions: Tactile spring-driven squish feedback on touch/pointer down via pressedScale and pressedMotion.
• Keyboard Navigation & Focus Rings: Zero-layout-impact ExpandableFocusRing with concentric corner contours, arrow navigation, Enter/Space activation, and keyboard reordering (Alt/Option + ArrowUp/ArrowDown).
• Sliver, Column, ListView & Reorderable Support: Provides Slivers, Column, ListView, and Reorderable wrappers out of the box.
• Physics & Animations: Spring-driven physics for expanding and collapsing with expressive presets via M3EMotion.
• Expressive Splash: Default InkSparkle splash effect for a modern Material 3 feel.
• Highly Customizable: Complete control over gaps, radii, colors, haptics, focus rings, and padding via M3EExpandableStyle.
• Global Theming: Set defaults for all expandable lists using M3EExpandableTheme.

📦 Installation #

Add m3e_expandable and material_ui to your pubspec.yaml:

dependencies:
  material_ui: ^1.0.0
  m3e_expandable: ^1.0.2

import 'package:material_ui/material_ui.dart';
import 'package:m3e_expandable/m3e_expandable.dart';

⚠️ Breaking Changes in v0.1.0 #

The API has been significantly refactored for better maintainability and more expressive styling options.

• Parameter Consolidation: Most visual parameters (outerRadius, innerRadius, gap, padding, colors, elevation) have been moved into the M3EExpandableStyle class.
• Haptic API: The haptic parameter has changed from an int (0-3) to the M3EHapticFeedback enum (none, light, medium, heavy).
• Constructor Changes:
  • The default constructor now takes a List<M3EExpandableData> for a data-driven approach.
  • Manual builders are now accessed via the .builder constructor.
• Builder Signatures:
  • headerBuilder now receives double progress instead of bool isExpanded.
  • bodyBuilder now receives double progress, allowing for custom animations during expansion.
• Icon API: showArrow and trailingIcon are replaced by expandIcon, collapseIcon, and iconPlacement inside M3EExpandableStyle.
• Motion API: openStiffness, openDamping, etc., are replaced by M3EMotion objects passed to expandMotion and collapseMotion.
• Shape API: selectedBorderRadius (BorderRadius) is replaced by expandedRadius (double) in the style configuration for uniform corner morphing.

🧩 Quick Start #

Data-Driven (Simple) #

Use M3EExpandableData for a quick setup with standard M3 layouts.

M3EExpandableCardList(
  data: [
    M3EExpandableData(
      title: 'Battery level low',
      subtitle: 'Plug in your device to avoid losing your work.',
      leading: const Icon(Icons.battery_alert),
      body: const Text('Your battery is at 10% and will run out soon.'),
    ),
    // ... more items
  ],
)

Manual Control (Builder) #

Use the .builder constructor for full control over the header and body content.

M3EExpandableCardList.builder(
  itemCount: 10,
  headerBuilder: (context, index, progress) => Text('Header $index (Progress: $progress)'),
  bodyBuilder: (context, index, progress) => Text('Body content for $index'),
)

Reorderable Expandable List #

Use M3EReorderableExpandableList for spring-physics reordering while preserving expandable card states.

List<M3EExpandableData> items = [
  M3EExpandableData(title: 'Task 1', body: const Text('Details for task 1')),
  M3EExpandableData(title: 'Task 2', body: const Text('Details for task 2')),
  M3EExpandableData(title: 'Task 3', body: const Text('Details for task 3')),
];

M3EReorderableExpandableList(
  data: items,
  buildDefaultDragHandles: true,
  onReorder: (oldIndex, newIndex) {
    setState(() {
      if (newIndex > oldIndex) newIndex -= 1;
      final item = items.removeAt(oldIndex);
      items.insert(newIndex, item);
    });
  },
)

📖 Detailed API Guide #

1. M3EExpandableData #

Defines content for data-driven constructors.

2. M3EExpandableStyle #

Complete visual and interaction configuration.

3. M3EMotion #

Spring physics presets for animations. All presets use specific stiffness and damping values to achieve their respective feels.

🏗️ Spatial Presets (Shape Morphing)

Used for animating the container shape and border radius.

✨ Effects Presets (Opacity/Scale)

Used for internal content animations like cross-fades.

🛠️ Custom Motion

Create a custom spring with specific physics:

M3EMotion.custom(stiffness: 380, damping: 0.75, snapToEnd: false)

4. M3EExpandableTheme #

Wrap your app to provide global defaults.

M3EExpandableTheme(
  data: M3EExpandableThemeData(
    style: M3EExpandableStyle(outerRadius: 32, gap: 4),
    expandMotion: M3EMotion.expressiveSpatialDefault,
    collapseMotion: M3EMotion.standardSpatialFast,
    allowMultipleExpanded: true,
  ),
  child: MyApp(),
)

5. M3EReorderableExpandableList #

A spring-physics reorderable expandable card list that combines full collapsible/expandable card functionality with dynamic destination placeholder slots, spring lift-off motion, bouncy neighbor displacement, and smooth snap settling.

6. Widget Parameters (Common) #

All list variants (CardList, CardColumn, SliverList, ReorderableList) share these core parameters:

7. ⌨️ Keyboard Shortcuts & Accessibility #

Cards support full keyboard navigation and zero-layout-impact focus indicators out of the box:

• Focus & Traversal: Navigate between items using Tab / Shift+Tab.
• Toggle Expansion: Press Enter or Space to toggle expand/collapse.
• Directional Expand / Collapse: Press ArrowRight or ArrowDown to expand; ArrowLeft or ArrowUp to collapse.
• Keyboard Reordering: In M3EReorderableExpandableList, press Alt + ArrowDown (or Option + ArrowDown) to reorder the item forward, and Alt + ArrowUp (or Option + ArrowUp) to reorder backward.

🐞 Found a bug? or ✨ You have a Feature Request? #

Feel free to open an Issue or Contribute to the project.

Hope You Love It!

Credits #

• Motor Pub Package for Expressive Animations
• Claude and Gemini for helping me with the code and documentation.

Radhe Radhe 🙏 #