An enhanced NestedScrollView offering overscroll support for both the nested and parent scroll views, ensuring a seamless scrolling experience.
Try it online: https://flutter-nested-scroll-view-plus.vercel.app
Installation:
flutter pub add nested_scroll_view_plus
Example usage:
import 'package:nested_scroll_view_plus/nested_scroll_view_plus.dart';
// Step 1: Replace `NestedScrollView` with `NestedScrollViewPlus`
NestedScrollViewPlus(
headerSliverBuilder: (context, innerScrolled) => <Widget>[
// ... insert your header sliver widgets here
],
body: CustomScrollView(
// Step 2: [๐จIMPORTANT] Set the physics of `CustomScrollView` to `AlwaysScrollableScrollPhysics`
physics: const BouncingScrollPhysics(
parent: AlwaysScrollableScrollPhysics(),
),
slivers: <Widget>[
// ... insert your body sliver widgets here
],
),
);
For additional examples, please visit the scroll_master repository. It includes features such as pull-to-refresh for NestedScrollView
, combined scrolling for scrollview and tabview, and more.
With the release of version 2.0.0, there are a few important changes that require action when upgrading from an earlier version.
For Deprecated Widgets:
If you are using OverlapAbsorberPlus
or OverlapInjectorPlus
in your code, follow these steps:
- Locate any header slivers wrapped with
OverlapAbsorberPlus
and remove theOverlapAbsorberPlus
wrapper. - Remove any
OverlapInjectorPlus
widget that was placed atop your scroll views.
For OverscrollBehavior:
Search your codebase for any instance of OverscrollType and replace it with OverscrollBehavior. This will ensure compatibility with the new naming convention.
By following these steps, you should be able to smoothly transition to version 2.0.0 without any significant issues. As always, it is recommended to test your application thoroughly after performing an upgrade to ensure that all features work as intended.
To access the inner or outer scroll controller of a NestedScrollViewPlus
, you can use a GlobalKey<NestedScrollViewStatePlus>
to get its state.
class _ExampleState extends State<Example> {
// 1. Create a GlobalKey
final GlobalKey<NestedScrollViewStatePlus> myKey = GlobalKey();
@override
Widget build(BuildContext context) {
return NestedScrollViewPlus(
// 2. Set the key to NestedScrollViewStatePlus
key: myKey,
// ...,
);
}
@override
void initState() {
super.initState();
WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
// 3. Access the inner or outer scroll controller using GlobalKey<NestedScrollViewStatePlus>
myKey.currentState!.innerController.addListener(_handleInnerScroll);
myKey.currentState!.outerController.addListener(_handleOuterScroll);
});
}
void _handleInnerScroll() {
final innerController = myKey.currentState!.innerController;
if (innerController.positions.length == 1) {
print('Scrolling inner nested scrollview: ${innerController.offset}');
}
}
void _handleOuterScroll() {
final outerController = myKey.currentState!.outerController;
if (outerController.positions.length == 1) {
print('Scrolling outer nested scrollview: ${outerController.offset}');
}
}
}
To preserve the scroll positions of inner CustomScrollViews
, you can add a PageStorageKey
to the CustomScrollView
widget. Here's an example:
CustomScrollView(
key: PageStorageKey<String>('unique-key'),
slivers: <Widget>[
// ...,
],
),
By assigning a unique key to the CustomScrollView
, Flutter's PageStorage
mechanism will store and restore the scroll position of the inner CustomScrollViews
, allowing you to maintain the scroll positions even when the widget tree is rebuilt.
If you are using an older version of Flutter, please follow these steps to install the appropriate branch from the old git repository.
dependencies:
custom_nested_scroll_view:
git:
url: https://github.com/idootop/custom_nested_scroll_view.git
# Choose the branch based on your local Flutter version
ref: flutter-3.7
The different branches support the following Flutter versions:
Git branch | Supported flutter versions |
---|---|
flutter-3.7 | >=3.7.0-13.0.pre |
flutter-3.4 | >=3.4.0-27.0.pre <3.7.0-13.0.pre |
flutter-3.4-pre | >=3.4.0-17.0.pre <3.4.0-27.0.pre |
flutter-3.0 | >=2.12.0-4.0.pre <3.4.0-17.0.pre |
flutter-2.x | <2.12.0-4.0.pre |
For more details, please visit the old documentation for CustomNestedScrollView
.