morphing_sheet #

A production-ready Flutter package for building spatially continuous, physics-based morphing interactions. Transform any widget — from a card, grid item, or list tile — into a fullscreen detail view with gesture-driven, deterministic animations. Zero dependencies beyond Flutter itself.

Inspired by Swiggy Instamart, Apple's container transforms, and Material Motion.

Table of Contents #

• Overview
• Key Features
• Three Interaction Paradigms
• Installation
• Quick Start
  • MorphingCard (Simplest)
  • MorphingCardCarousel
  • MorphingOverlay
  • MorphOverlayManager (Imperative)
• Architecture
  • Package Structure
  • Layer Responsibilities
  • Core Engine — MorphEngine
  • State Machine
  • Controllers
• API Reference
  • MorphController API
  • CardCarouselController API
  • OverlayMorphController API
• Configuration & Customization
• Animation System
• Physics & Gestures
• Performance
• Testing
• Version History
• Minimum Requirements
• License

Overview #

morphing_sheet provides a unified spatial morphing system for Flutter. At its core is MorphEngine — a pure-function interpolation engine that maps a single progress value (0.0 → 1.0) to every visual property: rect, radius, elevation, blur, scale, and content crossfade. This ensures all morph transitions are deterministic (State = f(progress)), with no implicit animation widgets, no AnimatedContainer, and no rebuild storms.

The package ships with three ready-to-use interaction paradigms, each built on top of the shared core engine:

Key Features #

🎯 Core Architecture #

• Single source of truth — One AnimationController drives all visual properties; no widget-level animations.
• Deterministic state machine — State = f(progress). No hidden state, no implicit UI mutations.
• Pure-function engine — MorphEngine is entirely static, side-effect free, and testable.
• State-management agnostic — All controllers extend ChangeNotifier; works with Provider, Riverpod, Bloc, or vanilla ListenableBuilder.
• Zero external dependencies — Only flutter/widgets.dart and flutter/material.dart.

🎨 Visual Effects #

• Rect morphing — Pixel-perfect interpolation from source widget to fullscreen.
• Corner radius animation — Rounded card → zero-radius fullscreen.
• Peak-and-drop elevation — Shadow peaks mid-transition for a physical "lift" effect.
• Background scrim — Semi-transparent barrier with configurable opacity.
• Background blur — Gaussian blur that intensifies with expansion.
• Background scale — Subtle zoom-out of underlying content during morph.
• Content crossfade — Collapsed content fades out, expanded content fades in, with configurable timing.
• Shared element transitions — Tag-based MorphShared widget for per-element animation (Hero-like, scoped to container).

🖐 Gesture System #

• Direction-locking — 16px threshold before axis is locked (horizontal vs. vertical).
• Rubber-band resistance — Elastic boundary feedback when dragging past limits.
• Velocity-aware snapping — Flick gestures resolve snap targets based on speed.
• Drag-to-collapse — Pull down from fullscreen to dismiss.
• Two-axis support — Simultaneous horizontal carousel swiping + vertical morph expansion.
• Back button integration — PopScope consumption when expanded.

⚡ Performance #

• RepaintBoundary isolation — Separate paint layers for background, scrim, morph surface, and content.
• Lazy content rendering — Only builds visible content (collapsed OR expanded, never both at rest).
• No AnimatedOpacity / AnimatedContainer — Raw Opacity and Transform widgets for zero overhead.
• Opacity culling — Content layers with opacity < 0.01 are excluded from the widget tree entirely.

Three Interaction Paradigms #

MorphingCard #

Tap a card → it expands from its exact on-screen position to fullscreen. Drag down or press back to collapse. Renders via Flutter's Overlay for correct z-ordering.

MorphingCardCarousel #

A centered card carousel with horizontal swiping between items and vertical drag-to-fullscreen. Includes a circular thumbnail selector bar. Custom CarouselScrollPhysics (no PageView physics).

MorphingOverlay #

Instamart-style contextual morph: tap a grid/list item → it morphs from its exact position into a centered floating card (with a bottom thumbnail selector) → drag up to fullscreen detail (with a sticky header). Seven-phase state machine: idle → appearing → cardMode → expanding → fullscreen → collapsing → disappearing → idle.

Installation #

dependencies:
  morphing_sheet: ^0.6.0

// Pick the import for your use case:
import 'package:morphing_sheet/morphing_surface.dart';        // MorphingCard + MorphOverlayManager
import 'package:morphing_sheet/morphing_card_carousel.dart';  // MorphingCardCarousel
import 'package:morphing_sheet/morphing_overlay.dart';        // MorphingOverlay (grid → card → full)

Quick Start #

1. MorphingCard — Simplest #

import 'package:morphing_sheet/morphing_surface.dart';

class ProductGrid extends StatefulWidget {
  @override
  State<ProductGrid> createState() => _ProductGridState();
}

class _ProductGridState extends State<ProductGrid>
    with SingleTickerProviderStateMixin {
  late final MorphController _controller;

  @override
  void initState() {
    super.initState();
    _controller = MorphController(vsync: this);
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MorphingFrame(
      controller: _controller,
      child: Scaffold(
        body: MorphingCard(
          controller: _controller,
          collapsedBuilder: (context, progress) => ProductCard(product),
          expandedBuilder: (context, progress) => ProductDetailPage(product),
          duration: const Duration(milliseconds: 450),
          dragToCollapse: true,
        ),
      ),
    );
  }
}

2. MorphingCardCarousel #

import 'package:morphing_sheet/morphing_card_carousel.dart';

MorphingCardCarousel<Product>(
  items: products,
  cardBuilder: (context, item, progress, index, isActive) {
    return ProductCard(item: item);
  },
  fullscreenBuilder: (context, item, progress) {
    return ProductDetail(item: item);
  },
  thumbnailBuilder: (context, item, isActive) {
    return Image.network(item.thumbUrl, fit: BoxFit.cover);
  },
)

3. MorphingOverlay (Flagship Demo) #

The premium "Instamart-style" contextual morph. Tap a grid/list item → it morphs from its exact position into a centered floating card (with carousel swiping) → drag up to fullscreen detail.

Features a 7-phase state machine: idle → appearing → cardMode → expanding → fullscreen → collapsing → disappearing → idle.

import 'package:morphing_sheet/morphing_overlay.dart';

// 1. Create controller (requires TickerProviderStateMixin)
final controller = OverlayMorphController(
  vsync: this,
  flickVelocityThreshold: 500.0, // Soft, premium physics
);

// 2. Wrap your layout with MorphingOverlay
MorphingOverlay<Product>(
  controller: controller,
  items: products,
  maxRadius: 16,
  maxElevation: 20,
  cardBuilder: (context, item, progress) => ProductCard(item: item, progress: progress),
  detailBuilder: (context, item, progress) => ProductDetail(item: item, progress: progress),
  child: CustomScrollView(
    slivers: [
      SliverGrid.builder(
        itemCount: products.length,
        itemBuilder: (context, index) {
          // 3. Wrap each item with MorphingSource
          return MorphingSource<Product>(
            controller: controller,
            item: products[index],
            itemIndex: index,
            child: ProductTile(products[index]),
          );
        },
      ),
    ],
  ),
)

Premium add-ons included in the example app:

• HeroProductImage: Shared visual element linking the grid, card, and sticky header.
• CarouselIndexSelector: Bottom-drawer thumbnail scroll bar that automatically hides during morphing.
• Card Lift: Elevation scaling during the transition to simulate a physical "lift" effect.

4. MorphOverlayManager — Imperative #

import 'package:morphing_sheet/morphing_surface.dart';

final manager = MorphOverlayManager(vsync: this);

// On tap:
manager.show(
  context: context,
  collapsedBuilder: (ctx, p) => ProductTile(product),
  expandedBuilder: (ctx, p) => ProductDetail(product),
);

// On dismiss:
manager.hide();

Architecture #

Package Structure #

lib/
 ├── morphing_surface.dart          # Barrel: core engine + MorphingCard + MorphOverlayManager
 ├── morphing_card_carousel.dart    # Barrel: MorphingCardCarousel + CardCarouselController
 ├── morphing_overlay.dart          # Barrel: MorphingOverlay + OverlayMorphController
 └── src/
      ├── core/                     # Shared foundation
      │    ├── morph_engine.dart     #   Pure-function interpolation (rect, radius, elevation, blur...)
      │    ├── morph_controller.dart #   Unified AnimationController wrapper + drag support
      │    ├── morph_phase.dart      #   MorphPhase enum + MorphState immutable snapshot
      │    ├── morph_origin.dart     #   MorphOrigin (source rect capture) + MorphOriginType
      │    └── morph_shared.dart     #   MorphShared tag-based shared element widget
      ├── controller/
      │    └── card_carousel_controller.dart  # Carousel-specific controller (vertical + horizontal)
      ├── models/
      │    ├── card_item.dart        #   CardItem<T> stable-identity data wrapper
      │    └── card_state.dart       #   CardCarouselState + CardPhase enum
      ├── animations/
      │    ├── card_morph_tween.dart  #   Card-specific interpolation helpers (delegates to MorphEngine)
      │    └── rect_morph_tween.dart  #   Rect-based overlay interpolation helpers
      ├── physics/
      │    └── carousel_physics.dart  #   CarouselScrollPhysics + CarouselSnapResolver
      ├── gestures/
      │    └── morph_drag_controller.dart  #  Direction-locking + rubber-band drag handling
      ├── overlay/
      │    ├── overlay_controller.dart        # OverlayMorphController (two AnimationControllers)
      │    ├── overlay_state.dart             # OverlayMorphState + OverlayPhase (7 phases)
      │    ├── overlay_morphing_container.dart # MorphingOverlay<T> container widget
      │    ├── morphing_source.dart           # MorphingSource<T> tap-capture wrapper
      │    ├── overlay_gesture_layer.dart     # Overlay gesture disambiguation
      │    └── morph_overlay_manager.dart     # Imperative MorphOverlayManager
      └── widgets/
           ├── morphing_surface.dart     # Base morph surface (rect + radius + elevation + crossfade)
           ├── morphing_card.dart        # MorphingCard flagship widget
           ├── morphing_frame.dart       # Background scale + blur wrapper
           ├── card_container.dart       # MorphingCardCarousel<T> main widget
           ├── card_stack_layer.dart      # Positioned active + adjacent card rendering
           ├── thumbnail_selector_bar.dart # Horizontally scrollable circular thumbnails
           ├── gesture_layer.dart        # Carousel gesture disambiguation
           └── background_layer.dart     # Scale + blur + barrier background

Total: 26 source files | 8 test files | 4 example apps

Layer Responsibilities #

Core Engine — MorphEngine #

The engine is an abstract final class with only static methods. Every visual property is a pure function of progress:

// Rect geometry
Rect  rect      = MorphEngine.morphRect(progress, startRect, endRect);
double left     = MorphEngine.morphLeft(progress, startLeft, endLeft);
double top      = MorphEngine.morphTop(progress, startTop, endTop);
double width    = MorphEngine.morphWidth(progress, startWidth, endWidth);
double height   = MorphEngine.morphHeight(progress, startHeight, endHeight);

// Visual properties
double radius    = MorphEngine.morphRadius(progress, startRadius: 16, endRadius: 0);
double elevation = MorphEngine.morphElevation(progress, peakElevation: 16);  // peaks at 0.5
double scrim     = MorphEngine.morphScrim(progress, maxOpacity: 0.5);
double blur      = MorphEngine.morphBlur(progress, maxBlur: 6.0);
double scale     = MorphEngine.morphScale(progress, minScale: 0.95);

// Content crossfade
double sourceAlpha = MorphEngine.sourceContentOpacity(progress);  // 1.0 → 0.0
double targetAlpha = MorphEngine.targetContentOpacity(progress);  // 0.0 → 1.0

State Machine #

MorphPhase (core — used by MorphingCard and MorphOverlayManager):

collapsed → expanding → expanded → collapsing → collapsed
                              ↕
                          dragging

CardPhase (carousel):

collapsedCard → transitioningToFull → fullscreen → transitioningToCard → collapsedCard

OverlayPhase (overlay — 7 phases):

idle → appearing → cardMode → expanding → fullscreen → collapsing → cardMode → disappearing → idle

Controllers #

API Reference #

MorphController API #

// Lifecycle
final controller = MorphController(
  vsync: this,
  expandDuration: const Duration(milliseconds: 420),
  collapseDuration: const Duration(milliseconds: 350),
  expandCurve: Curves.easeInOutCubic,
  collapseCurve: Curves.easeInOutCubic,
);

// Programmatic control
controller.expandFrom(origin: origin, targetRect: fullscreenRect);
controller.expand();
controller.collapse();

// Interactive drag
controller.startDrag();
controller.updateDrag(delta, availableHeight);
controller.endDrag(velocityPxPerSecond, availableHeight);

// Read-only state
controller.progress;     // 0.0 → 1.0
controller.phase;        // MorphPhase enum
controller.state;        // MorphState immutable snapshot
controller.origin;       // MorphOrigin?
controller.targetRect;   // Rect?
controller.currentRect;  // Rect? (interpolated at current progress)
controller.isCollapsed;  // bool
controller.isExpanded;   // bool
controller.isAnimating;  // bool
controller.isDragging;   // bool

CardCarouselController API #

final ctrl = CardCarouselController(vsync: this, itemCount: items.length);

// Vertical morph
ctrl.expand();
ctrl.collapse();
ctrl.onVerticalDragStart();
ctrl.onVerticalDragUpdate(delta, availableHeight);
ctrl.onVerticalDragEnd(velocity, availableHeight);

// Horizontal carousel
ctrl.setIndex(index);
ctrl.animateToIndex(index);
ctrl.resolveHorizontalSnap(velocity: v, displacement: d, cardWidth: w);

// State
ctrl.verticalProgress;  // 0.0 → 1.0
ctrl.currentIndex;      // int
ctrl.phase;             // CardPhase
ctrl.state;             // CardCarouselState

OverlayMorphController API #

// Requires TickerProviderStateMixin (two AnimationControllers)
final ctrl = OverlayMorphController(vsync: this);

// Selection
ctrl.selectItem(item, itemIndex: 0, originRect: rect, screenSize: size);
ctrl.dismiss();

// Vertical expand/collapse
ctrl.expand();
ctrl.collapse();

// Horizontal carousel
ctrl.setIndex(index);
ctrl.onHorizontalDragUpdate(delta);
ctrl.onHorizontalDragEnd(velocity, cardWidth);

// Back button
ctrl.handleBackButton();  // returns bool (consumed or not)

// State
ctrl.state;              // OverlayMorphState
ctrl.overlayProgress;    // appear/disappear: 0.0 → 1.0
ctrl.expandProgress;     // card→fullscreen: 0.0 → 1.0
ctrl.currentIndex;       // int
ctrl.phase;              // OverlayPhase (7 phases)
ctrl.selectedItem;       // Object?
ctrl.hasSelection;       // bool

Configuration & Customization #

MorphingCard #

MorphingCard(
  controller: controller,
  collapsedBuilder: (context, progress) => CardContent(),
  expandedBuilder: (context, progress) => DetailContent(),
  duration: const Duration(milliseconds: 450),       // expand/collapse duration
  expandCurve: Curves.easeInOutCubic,
  collapseCurve: Curves.easeInOutCubic,
  borderRadius: 16.0,                                // source corner radius
  maxElevation: 12.0,                                // peak shadow elevation
  surfaceColor: Colors.white,                         // card background
  dragToCollapse: true,                               // enable drag-down dismiss
  enableSharedElements: false,                        // MorphShared tag animations
  onExpanded: () {},                                  // callback
  onCollapsed: () {},                                 // callback
)

MorphingFrame (Background Effects) #

MorphingFrame(
  controller: controller,
  minScale: 0.94,     // background scale when fully expanded
  maxBlur: 5.0,       // background blur intensity
  child: Scaffold(...),
)

MorphingCardCarousel #

MorphingCardCarousel<T>(
  items: items,
  cardBuilder: (context, item, progress, index, isActive) => ...,
  fullscreenBuilder: (context, item, progress) => ...,
  thumbnailBuilder: (context, item, isActive) => ...,
  backgroundBuilder: (context, progress, index) => ...,
  controller: controller,                              // optional external controller
  cardHeightFraction: 0.75,
  cardWidthFraction: 0.85,
  maxRadius: 28.0,
  maxElevation: 12.0,
  expandDuration: const Duration(milliseconds: 350),
  collapseDuration: const Duration(milliseconds: 300),
  expandCurve: Curves.easeInOutCubic,
  collapseCurve: Curves.easeInOutCubic,
)

MorphOverlayManager #

MorphOverlayManager(
  vsync: this,
  borderRadius: 16.0,
  maxElevation: 16.0,
  scrimOpacity: 0.5,
  expandDuration: const Duration(milliseconds: 420),
  collapseDuration: const Duration(milliseconds: 420),
  expandCurve: Curves.easeInOutCubic,
  collapseCurve: Curves.easeInOutCubic,
)

Animation System #

All animations are driven by pure-function interpolation. No AnimatedWidget subclasses.

Interpolation Helpers #

Content Crossfade Timing #

progress:  0.0 ──── 0.35 ──── 0.4 ──── 0.7 ──── 1.0
source:    ████████████████████░░░░░░░░░░░░░░░░░░░░
target:    ░░░░░░░░░░░░░░░░░░██████████████████████
                         ↑ overlap zone (0.35–0.4)

Elevation Peak-and-Drop #

progress:  0.0 ─── 0.5 ─── 1.0
elevation: 4 ─── 16 ─── 0
                ↑ peak (mid-transition lift effect)

Physics & Gestures #

CarouselScrollPhysics #

Custom ScrollPhysics implementation (not PageScrollPhysics) with:

• Velocity-aware snapping — Flick above 600 px/s triggers immediate index change.
• Distance threshold — 30% card width drag triggers snap without velocity.
• Spring simulation — mass: 0.8, stiffness: 120, damping: 14.

CarouselSnapResolver #

Deterministic index resolution from velocity + displacement:

int targetIndex = CarouselSnapResolver.resolve(
  currentIndex: current,
  velocity: velocity,
  displacement: displacement,
  cardWidth: width,
  itemCount: count,
  velocityThreshold: 600.0,    // px/s
  distanceThreshold: 0.3,      // fraction of card width
);

MorphDragController #

Enhanced drag handler wrapping MorphController:

• Direction-locking — 12px threshold before axis commit.
• Rubber-band — 0.25× input scalar at boundaries.
• Axis tracking — Exposed via isVerticalLocked / isHorizontalLocked.

Velocity Snap Resolution (Vertical) #

const velocityThreshold = 1.5;   // normalized units/s
const progressThreshold = 0.5;   // progress midpoint

if (normVelocity.abs() > velocityThreshold) {
  shouldExpand = normVelocity > 0;    // fast flick decides
} else {
  shouldExpand = progress >= 0.5;     // position decides
}

Performance #

Testing #

The package includes 8 test files covering:

Run tests:

flutter test

Version History #

See CHANGELOG.md for detailed migration guides.

Minimum Requirements #

• Flutter >= 3.10.0
• Dart >= 3.10.4

License #

MIT — see LICENSE for details.