quick_list_builder

A lightweight and developer-friendly list widget for Flutter. QuickListBuilder replaces boilerplate ListView.builder code with a single, feature-rich widget that handles selection, async data, pagination, grid layout, section headers, skeleton loading, and more — with zero extra dependencies.

Features

  • 4 selection modes — none, radio, checkbox, switch toggle
  • Trailing or leading selection placement
  • Async fetcher — Future-based data source with built-in loading / error / empty states
  • Infinite scroll pagination — auto-loads the next page near the scroll end
  • Pull-to-refresh — RefreshIndicator wired automatically
  • Grid layout — drop-in GridView with layout: QuickListLayout.grid
  • Section headers — inline grouped headers via sectionHeaderBuilder
  • Skeleton loading — custom per-item placeholders during initial load
  • Programmatic controller — QuickListController for refresh, loadMore, insert, remove, replaceWhere
  • Custom builders — itemBuilder, titleBuilder, subtitleBuilder, leadingBuilder, trailingBuilder, radioBuilder, checkboxBuilder, switchBuilder
  • Dividers & separators — divider toggle, static separator, or per-index separatorBuilder
  • Animated item transitions — configurable animationDuration
  • Item enable/disable — per-item enabled state with 50 % opacity
  • Horizontal lists — scrollDirection: Axis.horizontal
  • List extension — myList.quickList(...) builds from any List<T> instantly
  • Zero extra dependencies

Installation

dependencies:
  quick_list_builder: ^0.0.3

import 'package:quick_list_builder/quick_list_builder.dart';

Quick start

Static list

final items = ['Apple', 'Banana', 'Cherry'];

QuickListBuilder<String>(
  items: items,
  divider: true,
  onItemTap: (item) => print('Tapped $item'),
)

Or use the List extension:

items.quickList(
  divider: true,
  onItemTap: (item) => print('Tapped $item'),
)

Selection modes

Radio

String? selected = 'Apple';

QuickListBuilder<String>(
  items: items,
  selectionMode: QuickListSelectionMode.radio,
  selectedItem: selected,
  onChanged: (val) => setState(() => selected = val as String),
)

Checkbox

List<String> selected = [];

QuickListBuilder<String>(
  items: items,
  selectionMode: QuickListSelectionMode.checkbox,
  trailingSelection: true,        // place checkbox on the right
  selectedItems: selected,
  onChanged: (val) => setState(() => selected = List<String>.from(val as List)),
)

Switch toggle

QuickListBuilder<String>(
  items: items,
  selectionMode: QuickListSelectionMode.switchToggle,
  trailingSelection: true,
  selectedItems: enabled,
  onChanged: (val) => setState(() => enabled = List<String>.from(val as List)),
)

Async data & pagination

Provide a fetcher instead of items to load data from an API. The widget handles loading, error, empty, and infinite-scroll pagination states automatically.

Future<QuickListPage<User>> _fetchUsers(int page, int pageSize) async {
  final json = await api.getUsers(page: page, limit: pageSize);
  return QuickListPage(
    items: json.map(User.fromJson).toList(),
    hasMore: json.length == pageSize,
  );
}

QuickListBuilder<User>(
  fetcher: _fetchUsers,
  pageSize: 20,
  enablePagination: true,
  enablePullToRefresh: true,
  titleBuilder: (user) => Text(user.name),
  subtitleBuilder: (user) => Text(user.email),
  leadingBuilder: (user) => CircleAvatar(child: Text(user.name[0])),
  emptyWidget: const Center(child: Text('No users found')),
  errorBuilder: (context, error, retry) => Center(
    child: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        Text('$error'),
        FilledButton(onPressed: retry, child: const Text('Retry')),
      ],
    ),
  ),
  endOfListWidget: const Center(
    child: Padding(
      padding: EdgeInsets.all(16),
      child: Text('— no more results —'),
    ),
  ),
)

Grid layout

Switch to a GridView with one parameter:

QuickListBuilder<Product>(
  fetcher: _fetchProducts,
  layout: QuickListLayout.grid,
  gridCrossAxisCount: 2,
  gridChildAspectRatio: 0.75,
  gridMainAxisSpacing: 8,
  gridCrossAxisSpacing: 8,
  itemBuilder: (context, product, index) => ProductCard(product),
)

Section headers

Group items under inline headers automatically:

QuickListBuilder<Contact>(
  items: contacts,          // must be pre-sorted by group
  sectionHeaderBuilder: (contact, index) => contact.department,
  titleBuilder: (contact) => Text(contact.name),
  subtitleBuilder: (contact) => Text(contact.role),
  leadingBuilder: (contact) => CircleAvatar(child: Text(contact.name[0])),
)

Use sectionHeaderWidgetBuilder for a fully custom header widget.

Skeleton loading

Show placeholder items while the first page loads:

QuickListBuilder<Post>(
  fetcher: _fetchPosts,
  skeletonCount: 6,
  skeletonBuilder: (context) => const ListTile(
    leading: _SkeletonCircle(),
    title: _SkeletonLine(width: double.infinity),
    subtitle: _SkeletonLine(width: 140),
  ),
  itemBuilder: (context, post, index) => PostTile(post),
)

Programmatic controller

Use QuickListController to refresh, paginate, or mutate items from outside the widget:

final _controller = QuickListController<String>();

// Attach
QuickListBuilder<String>(
  fetcher: _fetch,
  controller: _controller,
  ...
)

// Elsewhere
_controller.refresh();                        // reload from page 1
_controller.insert('New item', at: 0);        // optimistic insert
_controller.remove('Old item');               // optimistic remove
_controller.replaceWhere((e) => e == 'x', 'y'); // swap item

Custom item builder

Full control over each row:

QuickListBuilder<Order>(
  items: orders,
  itemBuilder: (context, order, index) => Card(
    margin: const EdgeInsets.symmetric(horizontal: 12, vertical: 4),
    child: ListTile(
      leading: Icon(
        order.isPaid ? Icons.check_circle : Icons.pending,
        color: order.isPaid ? Colors.green : Colors.orange,
      ),
      title: Text(order.title),
      subtitle: Text('\$${order.amount}'),
      trailing: Text(order.date),
    ),
  ),
)

Separators

// Built-in divider
QuickListBuilder<String>(items: items, divider: true)

// Static separator widget
QuickListBuilder<String>(
  items: items,
  separator: const Padding(
    padding: EdgeInsets.symmetric(horizontal: 16),
    child: Divider(height: 1),
  ),
)

// Per-index separator builder
QuickListBuilder<String>(
  items: items,
  separatorBuilder: (context, index, before, after) =>
      index == 2 ? const SizedBox(height: 24) : const Divider(),
)

Horizontal list

SizedBox(
  height: 120,
  child: QuickListBuilder<Category>(
    items: categories,
    scrollDirection: Axis.horizontal,
    separator: const SizedBox(width: 12),
    itemBuilder: (context, cat, index) => CategoryChip(cat),
  ),
)

Item enable / disable

QuickListBuilder<Plan>(
  items: plans,
  isItemEnabled: (plan) => plan.isAvailable,  // disabled items shown at 50 % opacity
  selectionMode: QuickListSelectionMode.radio,
  selectedItem: _selectedPlan,
  onChanged: (val) => setState(() => _selectedPlan = val as Plan),
  titleBuilder: (plan) => Text(plan.name),
  subtitleBuilder: (plan) => Text(plan.price),
)

Full API reference

Data source

Param Type Default Description
items List<T>? — Static list. Provide either items or fetcher
fetcher QuickListFetcher<T>? — Async page fetcher. Provide either items or fetcher
pageSize int 20 Items per page requested from fetcher
enablePagination bool true Auto-load next page on scroll
enablePullToRefresh bool true Wrap with RefreshIndicator
controller QuickListController<T>? — Programmatic controller

Item rendering

Param Description
itemBuilder Full custom item widget — overrides all other builders
titleBuilder Title widget for each item
subtitleBuilder Subtitle widget for each item
leadingBuilder Leading widget (left side)
trailingBuilder Trailing widget (right side)
sectionHeaderBuilder Returns a group header string for each item
sectionHeaderWidgetBuilder Custom widget for section header

Selection

Param Type Default Description
selectionMode QuickListSelectionMode none none, radio, checkbox, switchToggle
selectedItem T? — Currently selected item (radio / switch)
selectedItems List<T>? — Currently selected items (checkbox / switch)
trailingSelection bool false Place selection widget on the trailing side
isItemSelected bool Function(T)? — Custom equality check for selection state
radioBuilder builder — Fully custom radio widget
checkboxBuilder builder — Fully custom checkbox widget
switchBuilder builder — Fully custom switch widget
activeColor Color? — Active color for radio / checkbox
checkColor Color? — Check mark color for checkbox
checkboxShape OutlinedBorder? — Custom checkbox shape (e.g. CircleBorder)

Interaction

Param Type Description
onItemTap ValueChanged<T>? Called when an item is tapped
onItemLongPress ValueChanged<T>? Called on long press
onChanged ValueChanged<dynamic>? Selection change callback
isItemEnabled bool Function(T)? Per-item enabled state

Layout

Param Type Default Description
layout QuickListLayout list list or grid
gridCrossAxisCount int 2 Grid columns
gridChildAspectRatio double 1.0 Grid cell aspect ratio
gridMainAxisSpacing double 8 Grid row spacing
gridCrossAxisSpacing double 8 Grid column spacing
scrollDirection Axis vertical Scroll axis
shrinkWrap bool false Shrink-wrap the scroll view
physics ScrollPhysics? — Custom scroll physics
scrollController ScrollController? — External scroll controller
reverse bool false Reverse scroll direction
padding EdgeInsetsGeometry? — List padding

Separators

Param Type Default Description
divider bool false Show Divider between items
dividerColor Color? — Divider color
dividerThickness double? — Divider thickness
dividerIndent / dividerEndIndent double? — Divider indent
separator Widget? — Static separator widget. Overrides divider
separatorBuilder builder — Per-index separator. Highest priority

Item styling

Param Type Description
itemPadding EdgeInsetsGeometry? Padding inside each item
itemMargin EdgeInsetsGeometry? Margin around each item
itemBackgroundColor Color? Default item background
selectedItemBackgroundColor Color? Background when selected
itemBorderRadius BorderRadiusGeometry? Item corner radius
itemBorder BoxBorder? Item border
itemShadow List<BoxShadow>? Item shadow
animationDuration Duration Selection animation duration (default 200 ms)

State widgets

Param Description
loadingWidget Widget shown during initial load (overrides skeleton)
errorBuilder (context, error, retry) — custom error widget
emptyWidget Widget shown when list is empty
loadMoreWidget Widget shown at bottom while loading more pages
endOfListWidget Widget shown when no more pages remain
skeletonCount Number of skeleton items to show during initial load
skeletonBuilder Builder for each skeleton item

QuickListController

final controller = QuickListController<T>();

controller.refresh();                           // reload from page 1
controller.loadMore();                          // load next page manually
controller.insert(item, at: 0);                 // insert at index
controller.remove(item);                        // remove by equality
controller.replaceWhere((e) => test(e), newItem); // conditional replace
controller.items;       // current item list (unmodifiable)
controller.isLoading;   // true during initial load
controller.isLoadingMore; // true while loading a page
controller.hasMore;     // whether more pages exist
controller.error;       // last initial-load error, if any

License

MIT

Libraries

main
quick_list_builder