gap2 #

A small but powerful Flutter layout primitive for intentional spacing.

gap2 provides axis-aware spacing widgets that work consistently across Flex layouts, Scrollables, and Slivers, with a clean, predictable API and native sliver support.

Overview #

Spacing is one of the most common layout needs in Flutter, yet it is often handled inconsistently using SizedBox, Spacer, or ad-hoc solutions.

gap2 solves this by providing dedicated spacing primitives that:

• Take space only along the parent’s main axis
• Work correctly in Row and Column
• Work inside Scrollable widgets like ListView
• Provide native sliver spacing without adapters
• Fail loudly and predictably when used incorrectly

Features #

• Gap — fixed spacing along the parent axis
• MaxGap — flexible spacing with an upper bound
• SliverGap — native sliver spacing for CustomScrollView
• Axis-aware behavior with no configuration
• Clean error messages for invalid usage
• Shared internal layout model for correctness

Installation #

Add gap2 to your pubspec.yaml:

dependencies:
  gap2: ^1.0.0

Then run:

flutter pub get

Usage #

Gap #

Gap inserts a fixed amount of space along the layout’s main axis.

Row(
  children: const [
    Text('Left'),
    Gap(16),
    Text('Right'),
  ],
);

In a vertical layout:

Column(
  children: const [
    Text('Above'),
    Gap(24),
    Text('Below'),
  ],
);

Inside a scrollable:

ListView(
  children: const [
    Text('Item A'),
    Gap(16),
    Text('Item B'),
  ],
);

MaxGap #

MaxGap behaves like a Spacer with a maximum extent.

Row(
  children: const [
    Text('A'),
    MaxGap(40),
    Text('B'),
  ],
);

The gap will expand if space is available, but never exceed the given value.

SliverGap #

For sliver layouts, use SliverGap inside a CustomScrollView.

CustomScrollView(
  slivers: const [
    SliverToBoxAdapter(child: Text('Item A')),
    SliverGap(24),
    SliverToBoxAdapter(child: Text('Item B')),
  ],
);

SliverGap contributes directly to sliver layout and scroll extent without wrapping box widgets in adapters.

How axis resolution works #

gap2 determines its axis automatically:

• Inside a Column → vertical spacing
• Inside a Row → horizontal spacing
• Inside a Scrollable → based on scroll direction

If Gap is used outside of these contexts, it throws a clear runtime error. This prevents silent layout bugs and makes intent explicit.

📖 Example #

A minimal example using all gap types:

import 'package:flutter/material.dart';
import 'package:gap2/gap2.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Column(
          children: const [
            Text('Top'),
            Gap(20),
            Text('Middle'),
            MaxGap(30),
            Text('Bottom'),
          ],
        ),
      ),
    );
  }
}

🤔 Why gap2? #

Compared to ad-hoc spacing solutions, gap2:

• Avoids mixing layout intent with visual widgets
• Works identically in box and sliver worlds
• Makes spacing explicit and self-documenting
• Scales from simple UIs to complex scroll views
• Is actively maintained

It is designed as a layout primitive, not just a convenience widget.

📜 License #

MIT License.

💬 Contributing #

Issues, suggestions, and pull requests are welcome.