EZ Custom Scroll View #

A crash-safe, self-aware drop-in replacement for Flutter's CustomScrollView that automatically handles unbounded constraints in Column, Row, Flex, and nested scroll views.

🛑 The Problem #

Flutter's standard CustomScrollView attempts to expand to fill all available space along its scrolling axis. When placed inside a parent with unbounded constraints, Flutter throws a fatal runtime exception that crashes your app with a red screen:

• Placing a vertical scroll view directly inside a Column or Flex.
• Placing a horizontal scroll view directly inside a Row or Flex.
• Nesting inside an unconstrained parent such as UnconstrainedBox or another unconstrained scroll view.

Common fatal errors in standard Flutter:

"Vertical viewport was given unbounded height."
"Horizontal viewport was given unbounded width."
"RenderBox was not laid out: RenderViewport... NEEDS-PAINT NEEDS-COMPOSITING-BITS-UPDATE"

✅ The EZ Solution #

EzCustomScrollView intercepts unbounded constraints before they cause a crash:

• Defensive Fallback Sizing: Automatically calculates a safe, bounded dimension (e.g., 50% of available screen height/width) so the widget renders visibly and cleanly.
• Developer Diagnostics (Debug Mode):
  • Logs a structured, actionable FlutterError explaining the exact parent culprit (e.g., Column, Row, UnconstrainedBox) and how to permanently fix it.
  • Highlights the problematic widget with a visible red outline border so developers instantly spot layout errors during development.
• Silent Protection (Release Mode): Silently applies the fallback size so your end users never experience a red screen of death in production.
• 100% Drop-in Parity: Supports all standard CustomScrollView properties (slivers, physics, controller, shrinkWrap, hitTestBehavior, etc.).

✨ Features #

• Omni-Directional Crash Prevention: Safeguards both vertical (height) and horizontal (width) unbounded viewports.
• Culprit Ancestor Inspection: Automatically inspects the widget tree to inform you which widget (Column, Row, Flex, etc.) caused the constraint violation.
• Customizable Fallbacks: Override default screen-percentage fallback sizing with fallbackHeight and fallbackWidth.
• Diagnostic Telemetry: Optional onUnboundedDetected callback for custom logging, analytics, or assertions.
• Zero External Dependencies: Built entirely with Flutter framework primitives.

📦 Installation #

flutter pub add ez_custom_scroll_view

🚀 Usage #

Simply replace CustomScrollView with EzCustomScrollView.

1. Vertical Example (Safe inside Column) #

In standard Flutter, this causes an instant crash. With EzCustomScrollView, it safely renders and alerts you in the debug console:

Column(
  children: [
    const Text('Header'),
    EzCustomScrollView(
      slivers: [
        SliverList.builder(
          itemCount: 20,
          itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
        ),
      ],
    ),
  ],
)

2. Horizontal Example (Safe inside Row) #

Row(
  children: [
    const Text('Sidebar'),
    EzCustomScrollView(
      scrollDirection: Axis.horizontal,
      slivers: [
        SliverToBoxAdapter(
          child: Container(width: 300, color: Colors.blue),
        ),
      ],
    ),
  ],
)

3. Recommended Production Fix #

While EzCustomScrollView prevents crashes, best practice in production is to provide bounded constraints using Expanded or explicit dimensions:

Column(
  children: [
    const Text('Header'),
    Expanded(
      child: EzCustomScrollView(
        slivers: [
          SliverGrid.count(
            crossAxisCount: 2,
            children: List.generate(20, (index) => Card(child: Center(child: Text('$index')))),
          ),
        ],
      ),
    ),
  ],
)

4. Custom Fallback & Diagnostic Callback #

EzCustomScrollView(
  fallbackHeight: 300.0,
  fallbackWidth: 250.0,
  showDebugIndicator: true,
  onUnboundedDetected: ({required isWidthUnbounded, required isHeightUnbounded, required culprit}) {
    debugPrint('Layout warning: Unbounded dimension in $culprit');
  },
  slivers: [
    SliverToBoxAdapter(child: Text('Custom bounded scroll')),
  ],
)

🤝 Contributing #

Contributions are welcome! Please feel free to open an issue or submit a pull request on GitHub.

📜 License #

MIT License - see the LICENSE file for details.