Collapsing Headers and Tabbed Views: NestedScrollView Patterns in Flutter
Master NestedScrollView in Flutter to synchronize collapsible SliverAppBars with tabbed scrollable views like TabBarView without scroll position conflicts.
Published on • November 9, 2026
AI Assistant

Building user profiles, detail pages, or media feeds often requires a flexible hero header (such as a cover photo, title, and action buttons) that collapses smoothly when scrolling through nested tabbed lists (such as ListView or GridView inside a TabBarView).
If you attempt to place a CustomScrollView inside another scroll view, both widgets fight for gesture events. Flutter resolves this architectural problem through NestedScrollView.
The Inner vs Outer Scroll Controller Architecture
NestedScrollView splits scrolling coordination into two parts:
- Outer Scroll Controller (
headerSliverBuilder): Controls outer sliver components likeSliverAppBaror header widgets. - Inner Scroll Controller (
body): Coordinates child scroll views inside the tabbed body view.
To prevent inner list controllers from hijacking scroll gestures from the header, child list views inside NestedScrollView must pass PrimaryScrollController.of(context) or rely on NestedScrollView’s internal scroll controller automatically.
Complete NestedScrollView Example with TabBarView
import 'package:flutter/material.dart';
class ProfileScreen extends StatelessWidget {
const ProfileScreen({super.key});
@override
Widget build(BuildContext context) {
return DefaultTabController(
length: 2,
child: Scaffold(
body: NestedScrollView(
headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
return <Widget>[
SliverOverlapAbsorber(
handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
sliver: SliverAppBar(
expandedHeight: 220.0,
pinned: true,
floating: true,
forceElevated: innerBoxIsScrolled,
flexibleSpace: const FlexibleSpaceBar(
title: Text('Jane Doe'),
background: Image(
image: NetworkImage('https://picsum.photos/600/300'),
fit: BoxFit.cover,
),
),
bottom: const TabBar(
tabs: [
Tab(icon: Icon(Icons.grid_on), text: 'Posts'),
Tab(icon: Icon(Icons.bookmark_border), text: 'Saved'),
],
),
),
),
];
},
body: TabBarView(
children: [
_buildTabList('Posts Tab', Colors.blue.shade50),
_buildTabList('Saved Tab', Colors.amber.shade50),
],
),
),
),
);
}
Widget _buildTabList(String title, Color bgColor) {
return Builder(
builder: (BuildContext context) {
return CustomScrollView(
key: PageStorageKey<String>(title), // Preserves tab scroll position
slivers: [
SliverOverlapInjector(
handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
),
SliverPadding(
padding: const EdgeInsets.all(8.0),
sliver: SliverList(
delegate: SliverChildBuilderDelegate(
(context, index) {
return Card(
color: bgColor,
child: ListTile(
leading: CircleAvatar(child: Text('${index + 1}')),
title: Text('$title Item #${index + 1}'),
),
);
},
childCount: 30,
),
),
),
],
);
},
);
}
}
Key Helper Slivers Explained
SliverOverlapAbsorber: Wraps theSliverAppBarinheaderSliverBuilder. It measures the pixel height of pinned elements (like theTabBar) and communicates this overlap to the inner view.SliverOverlapInjector: Placed at the top of inner scroll views. It injects top padding equal to the height absorbed bySliverOverlapAbsorber, ensuring list items are never hidden beneath pinned app bars.PageStorageKey: Attaching aPageStorageKeyto each tab’s scroll view retains scroll position independently when switching back and forth between tabs.
Takeaway: NestedScrollView cleanly unifies outer collapsible headers and inner tabbed views into a synchronized, single-gesture scroll experience.