CustomStack

An enhanced Flutter Stack widget with debugging capabilities and percentage-based positioning utilities.

Features

  • All standard Stack functionality (alignment, clipBehavior, fit)
  • Visual debugging with customizable borders
  • Percentage-based positioning helper method
  • Runtime validation for empty children
  • Demo showcasing different positioning techniques
  • Support for both absolute and relative positioning

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  apptomate_custom_stack: ^0.0.1

Usage

Basic Usage

CustomStack(
  alignment: Alignment.center,
  children: [
    BackgroundWidget(),
    Positioned(child: OverlayWidget()),
  ],
)

Percentage Positioning

LayoutBuilder(
  builder: (context, constraints) {
    return CustomStack(
      children: [
        BackgroundWidget(),
        CustomStack.relativePositioned(
          topPercent: 0.1,
          leftPercent: 0.1,
          width: 100,
          height: 100,
          parentSize: Size(constraints.maxWidth, constraints.maxHeight),
          child: OverlayWidget(),
        ),
      ],
    );
  },
)

Available Parameters

Parameter Type Default Description
children List required Widgets to stack (must not be empty)
alignment AlignmentGeometry topStart How to align non-positioned children
clipBehavior Clip hardEdge Content clipping behavior
fit StackFit loose How to size non-positioned children
debugPaint bool false Shows debug borders when true
debugColor Color Colors.red Color for debug borders

Positioning Helper Parameters

The relativePositioned static method accepts:

Parameter Type Description
top/bottom/left/right double? Absolute positioning
topPercent/bottomPercent/etc double? Percentage positioning (0.0-1.0)
width/height double? Child dimensions
parentSize Size required
child Widget required

Demo

The package includes a CustomStackWidget demo that shows three configurations:

  1. Basic Stack with absolute positioning
  2. Percentage-based positioning
  3. Debug mode with visible stack bounds

To run the demo:

void main() {
  runApp(MaterialApp(
    home: CustomStackWidget(),
  ));
}

Implementation Details

The widget:

  1. Wraps Flutter's core Stack functionality
  2. Adds optional debug painting
  3. Provides static helper for percentage positioning
  4. Validates against empty children lists

Best Practices

  1. Use LayoutBuilder with percentage positioning
  2. Enable debugPaint during layout development
  3. Combine absolute and percentage positioning carefully
  4. Consider clipBehavior for overflowing content
  5. Use the alignment property for non-positioned children

Comparison with Flutter's Stack

Feature Flutter Stack CustomStack
Basic stacking Yes Yes
Debug visualization Manual Built-in
Percentage positioning Manual Helper method
Empty children validation No Yes
Code organization Basic More structured

Common Use Cases

  • Overlay UIs and floating elements
  • Complex layout compositions
  • Responsive designs with percentage positioning
  • Debugging layout issues
  • Building custom stacked components

Libraries

apptomate_custom_stack