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.

Features
- Pure RenderBox Architecture (v2.0): Powered by
RenderOverlapStack&RawOverlapStackfor maximum rendering performance, zero layout-pass latency, and fullIntrinsicWidth/IntrinsicHeightmeasurement support. - Responsive & Adaptive: Automatically calculates how many items can fit and adjusts spacing smoothly between
minSpacingandmaxSpacing. - Horizontal & Vertical: Supports both
Axis.horizontalandAxis.vertical. - Pixel or Ratio Gap: Use fractional ratios (
minSpacing/maxSpacing) or explicit pixel offsets viaOverlapStack.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—with corresponding hit-test order. - Overflow Counter (
infoBuilder): Built-in indicator callback that shows how many items couldn't fit (e.g.+5). - On-demand Rendering:
OverlapStack.builderonly 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),
),
);
},
)
3. Low-Level Render Box (RawOverlapStack)
For custom layout engines or specialized rendering pipelines where you want direct RenderBox access without any widget abstractions:
RawOverlapStack(
direction: Axis.horizontal,
itemSize: const Size(40, 40),
textDirection: TextDirection.ltr,
children: const [
CircleAvatar(child: Text('1')),
CircleAvatar(child: Text('2')),
],
)
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
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.