grouped_list

v6.0.0

A Flutter ListView where the list items can be grouped into sections.

Package archive: https://pubdev.letsnova.ru/api/archives/grouped_list/6.0.0.tar.gz

Installdart pub add grouped_list

Readme Changelog Versions

Readme

Grouped list package for Flutter.

A flutter ListView in which list items can be grouped to sections.

Features

Sound null safety support!
Easy creation of chat dialog.
List Items can be separated in groups.
For the groups an individual header can be set.
Almost all fields from ListView.builder available.

Getting Started

Add the package to your pubspec.yaml:

 grouped_list: ^6.0.0

In your dart file, import the library:

import 'package:grouped_list/grouped_list.dart';

Instead of using a ListView create a GroupedListView Widget:

 GroupedListView<dynamic, String>(
                   elements: _elements,
                   groupBy: (element) => element['group'],
                   groupSeparatorBuilder: (String groupByValue) => Text(groupByValue),
                   itemBuilder: (context, dynamic element) => Text(element['name']),
                   itemComparator: (item1, item2) => item1['name'].compareTo(item2['name']), // optional
                   useStickyGroupSeparators: true, // optional
                   floatingHeader: true, // optional
                   order: GroupedListOrder.ASC, // optional
                   footer: Text("Widget at the bottom of list"), // optional
                 ),

Parameters:

Name	Description	Required	Default value
`elements`	A list of the data you want to display in the list	required	-
`groupBy`	Function which maps an element to its grouped value	required	-
`itemBuilder` / `indexedItemBuilder` / `interdependentItemBuilder` / `grouItemBuilder`	Function which returns an Widget which defines the item. * `indexedItemBuilder` provides the current index as well. * `interdependentItemBuilder` provides the previous and next items as well. * `groupItemBuilder` provides information if the item is the first or last element inside a group. `indexedItemBuilder` is preferred over `interdependentItemBuilder` and `interdependentItemBuilder` is preferred over`itemBuilder`.	yes, either of them	-
`groupSeparatorBuilder` / `groupHeaderBuilder`	Function which returns a Widget which defines the group headers. While `groupSeparatorBuilder` gets the `groupBy`-value as parameter `groupHeaderBuilder` gets the whole element. If both are defined `groupHeaderBuilder` is preferred	yes, either of them	-
`groupStickyHeaderBuilder`	Function which returns a Widget which defines the sticky group header, when `useStickyGroupSeparators` is `true`. If not defined `groupSeparatorBuilder` or `groupHeaderBuilder` will be used as described above.	no	-
`useStickyGroupSeparators`	When set to true the group header of the current visible group will stick on top	no	`false`
`floatingHeader`	Whether the sticky group header float over the list or occupy it's own space	no	`false`
`stickyHeaderBackgroundColor`	Defines the background color of the sticky header. Will only be used if `useStickyGroupSeparators` is used	no	`Color(0xffF7F7F7)`
`separator`	A Widget which defines a separator between items inside a group	no	no separator
`groupComparator`	Can be used to define a custom sorting for the groups. Otherwise the natural sorting order is used	no	-
`itemComparator`	Can be used to define a custom sorting for the elements inside each group. Otherwise the natural sorting order is used	no	-
`order`	Change to `GroupedListOrder.DESC` to reverse the group sorting	no	`GroupedListOrder.ASC`
`footer`	Widget at the bottom of the list	no	-

Also the fields from ListView.builder can be used.

Highlight - SilverGroupedList

Now supporting a grouped list based on a silver list. Just use SilverGroupedListView instead of GroupedListView. An example can be found under example/lib/example_silver. Note that some options of the GroupedListView are currently not available in SilverGroupedListView.

Highlight - Chat Dialog

Easy creation of chat dialogs. Just set the option reverse to true and order to GroupedListOrder.DESC. A full example can be found in the examples. The list will be scrolled to the end in the initial state and therefore scrolling will be against redeaing direction.

My other packages :

For easy creation of chat-like dialogs:

Check out my other package StickyGroupedList, which is based on the scrollable_positioned_list.

Changelog

[6.0.0] - 27.06.2024

Features:

feat: interdependent items builder GH-175
feat: add groupStickyHeaderBuilder GH-126
feat: added footer widget GH-189
feat: group section style GH-206

Bugfixes:

fix: distinct key parent child GH-171
fix RangeError when _sortedElements is empty GH-164
fix: wrong initial sticky header GH-198

[5.1.3] - 09.04.2023

Prepare for dart 3

[5.1.2] - 18.06.2022

Documentation improvements

[5.1.1] - 28.05.2022

Support older sdk versions

[5.1.0] - 28.05.2022

Make package backwards compatible to Flutter < 3.0.0
Bugfix: package does not modify passed element list anymore

[5.0.1] - 18.05.2022

Bugfix: Fix lint error

[5.0.0] - 18.05.2022

Feature: Upgrade to flutter 3.0 and use flutter_lints Pull Request #148
Bugfix: Fixes update to version 3.0 of flutter Pull Request #147
Bugfix: Resolve out of range error Pull Request #138

[4.2.0] - 04.02.2022

Bugfixes: Fix bug where item is rebuild every time state changes Pull Request #132

[4.1.0] - 22.07.2021

New feature: Silver support Pull Request #112
Bugfixes: Fix bug where a out of range error could appear Pull Request #110

[4.0.0] - 27.03.2021

Null safety

[4.0.0-nullsafety.1] - 20.11.2020

Update example to support null safety
Add pedantic for code analysis
Bugfixes: Fix bug where removeListener is called on null Issue #64

[4.0.0-nullsafety.0] - 20.11.2020

New feature: Add support for null safety.

[3.7.0] - 15.11.2020

New feature: Add new options from ListView.
Bug fixes: reverse option works with empty list

[3.6.0] - 14.11.2020

New feature: Add reverse option from ListView.

[3.5.0] - 19.09.2020

New feature custom sorting. Added two new options groupComparator and itemComparatorwhich can be used for comparison between two groups and items. If used the functions will be used for sorting the list.

[3.4.0] - 06.09.2020

New option groupHeaderBuilder: Same as groupSeparatorBuilder but will get the whole element instead of just the groupBy value.
New option stickyHeaderBackgroundColor: If useStickyGroupSeparators used a custom background color can be set.

[3.3.0] - 24.07.2020

Fix performance issue: Don't rebuild widget when sticky header changes.

[3.2.3] - 04.07.2020

Add code documentation

[3.2.2] - 26.06.2020

Fixed readme

[3.2.1] - 26.06.2020

Improved documentation
Improved example

[3.2.0] - 23.06.2020

Fixed performance issue when sticky group headers are actived. Widget now rebuilds only when necessary

[3.1.0] - 21.05.2020

Sticky Headers now by default disabled.

[3.0.1] - 18.05.2020

Bugfix: error when groupby value not comparable.
Bugfix: only set state when needed.

[3.0.0] - 05.05.2020

New Feature: Floating Header - Sticky Headers can now float over the list. Set floatingHeader to true.
Sticky Headers now by default active. Can be disabled by setting useStickyGroupSeparators to false.
Bugfix: The Widget can now be used in SliverChildListDelegate.

[2.3.1] - 04.05.2020

Bugfix: dispose controller only if not set throgh the widet.

[2.3.0] - 06.04.2020

New Feature: Indexed item builder. You can now define indexedItemBuilder instead of itemBuilder. The new method additionally provides the the current index as attribute.

[2.2.0] - 04.04.2020

Sorting items inside groups according to its comparable implmentation or alphabetical order.
Fixed bug where items rendered wrong

[2.1.0] - 02.04.2020

Fixed bug where wrong headers are displayed while using sticky headers.

[2.0.2] - 28.03.2020

Documentation

[2.0.1] - 28.03.2020

Bugfix: If no separator was specified a divider was rendered.
Bugfix: Adding items dynamically to an existing group led to a new group to be created.

[2.0.0] - 18.03.2020

New Feature: Sticky Headers! ** To use the sticky header set useStickyGroupSeparators to true. ** The parameter elements is now required.
Due to potential beaking changes the feature comes with a new major release.

[1.3.1] - 12.03.2020

Bugfix: The order option also works for groups which aren't comparable.

[1.3.0] - 10.03.2020

Add order option to the widget. With this the sorting of the groups can be reversed.

[1.2.1] - 18.08.2019

Improved documentary

[1.2.0] - 15.08.2019

Widget sort the list elements now according the groupByvalue. Can be switched off through the parameter sort

[1.1.0] - 14.08.2019

Added example
Edited readme and package description

[1.0.0] - 13.08.2019

Initial release