Pub Version GitHub License GitHub GitHub

OverlapStack intelligently stacks your widgets, allowing them to partially overlap for a compact, responsive, and visually interesting layout. This space-saving solution is perfect for user lists, avatar piles, participant presences, or any situation where you want to showcase multiple elements in limited space.

Preview

Features

  • Responsive & Adaptive: Automatically calculates how many items can fit and adjusts spacing smoothly between minSpacing and maxSpacing.
  • Horizontal & Vertical: Supports both Axis.horizontal and Axis.vertical.
  • Pixel or Ratio Gap: Use fractional ratios (minSpacing/maxSpacing) or explicit pixel offsets via OverlapStack.gap(...) / OverlapStack.gapBuilder(...).
  • RTL & Bidirectional Ready: Native Right-to-Left language layout awareness via Flutter's Directionality.
  • Accessible (a11y): Built-in semantic screen-reader announcements via semanticsLabel.
  • ShrinkWrap Support: Optionally shrink-wraps along the main axis via shrinkWrap: true.
  • Flexible Z-Ordering (leadIndex): Control which item is layered on top—the first item, the last item, or a middle item as the apex.
  • Overflow Counter (infoBuilder): Built-in indicator callback that shows how many items couldn't fit (e.g. +5).
  • On-demand Rendering: OverlapStack.builder only instantiates widgets that actually fit on screen.
  • Safe in All Layouts: Handles bounded layouts as well as unbounded parents (e.g. Row, Column, ListView) cleanly.

Usage

1. Basic Explicit Stack

OverlapStack(
  minSpacing: 0.5,
  maxSpacing: 0.8,
  itemSize: const Size(40, 40),
  children: const [
    CircleAvatar(child: Text('A')),
    CircleAvatar(child: Text('B')),
    CircleAvatar(child: Text('C')),
  ],
)

2. Dynamic Avatar Stack with Overflow Counter (.builder)

OverlapStack.builder(
  itemCount: 25,
  itemLimit: 8,
  itemSize: const Size.square(40),
  minSpacing: 0.5,
  maxSpacing: 0.8,
  leadIndex: 0, // First item on top
  align: OverlapStackAlign.start,
  itemBuilder: (context, index) {
    return CircleAvatar(
      radius: 20,
      backgroundImage: NetworkImage('https://i.pravatar.cc/100?u=$index'),
    );
  },
  infoBuilder: (context, remaining) {
    return CircleAvatar(
      radius: 20,
      backgroundColor: Colors.blueGrey,
      child: Text(
        '+$remaining',
        style: const TextStyle(fontSize: 12, color: Colors.white),
      ),
    );
  },
)

Parameters Reference

Parameter Type Default Description
direction Axis Axis.horizontal Main layout axis (horizontal or vertical).
align OverlapStackAlign .center Main-axis alignment (start, center, end).
minSpacing double 0.5 Minimum spacing ratio relative to item extent (e.g. 0.5 = 50% overlap).
maxSpacing double 0.8 Maximum spacing ratio relative to item extent (e.g. 0.8 = 20% overlap).
leadIndex int -1 Which item is on top: -1 for last item, 0 for first item, or > 0 for middle apex.
infoIndex int -1 Slot index for the infoBuilder widget (-1 = last slot).
infoBuilder OverlapStackInfoBuilder? null Callback to display remaining items indicator when not all fit.
itemLimit int -1 Hard cap on items displayed (-1 for unlimited).
itemSize Size? null Dimensions of an individual item.
clipBehavior Clip Clip.none Clipping behavior of the underlying stack.
shrinkWrap bool false Whether to shrink-wrap the stack extent along the main axis.
semanticsLabel String? null Accessibility label for screen readers (defaults to '$itemCount items').

Sponsoring

Buy Me A Coffee Ko-Fi

If this package or any other package I created is helping you, please consider sponsoring me so that I can take time to maintain and improve these packages.

Libraries

overlap_stack