flutter_blocx

Zero-Boilerplate Flutter UI Widgets for Paginated Lists, Grids, Slivers, Reactive Forms & Screen Management
The official Flutter presentation layer for blocx_core.

Why flutter_blocx? • BlocX Ecosystem • Installation • Collections & Grids • Forms • Screen Manager • ← blocx_core

Why flutter_blocx? #

Most Flutter apps don't become difficult to maintain because of complex animations—they become difficult to maintain because every data-driven screen repeatedly wires the same UI plumbing:

• Attaching and disposing ScrollControllers to trigger infinite pagination
• Coordinating loading, empty, error, pull-to-refresh, and search states
• Wiring BlocConsumers for item selection, row expansion, highlighting, and deletion spinners
• Creating, hydrating, and disposing TextEditingController and FocusNode maps for every form
• Displaying validation errors, async uniqueness spinners, and duplicate-submit guards
• Listening for snackbar, full-page error, and route-pop side effects

flutter_blocx eliminates that UI plumbing. Paired with blocx_core, you declare what your screen renders—and let the host state handle the controllers, listeners, pagination triggers, and side effects.

Before vs. After #

class _ProductsScreenState extends State<ProductsScreen> {
  // Manual ScrollController + _onScroll threshold math
  // Manual TextEditingController for search + dispose()
  // Manual BlocProvider + nested BlocConsumers
  // Manual if (isLoading) ... else if (isEmpty) ...
  // Manual RefreshIndicator + load-more footer
  // Manual snackbar / error page / pop listeners
}

class _ProductsScreenState
    extends BlocxCollectionWidgetState<ProductsScreen, ProductEntity, void> {
  @override
  BlocxCollectionBloc<ProductEntity, void> get generateBloc => ProductsBloc();

  @override
  Widget? topWidget(BuildContext context, BlocxCollectionState<ProductEntity> state) =>
      searchField();

  @override
  Widget itemBuilder(BuildContext context, ProductEntity item) =>
      ProductCard(item: item);
}

The BlocX Ecosystem: Better Together #

flutter_blocx is designed specifically to work hand-in-hand with blocx_core. Using both packages together gives you a cohesive, end-to-end architecture where domain logic stays 100% pure Dart and Flutter widgets remain declarative and concise:

Always install both packages together in your Flutter project so your BLoCs, UseCases, and Flutter screens share the same strongly typed contracts.

Feature Highlights #

• 📋 Collection Host & 6 Layout Engines (list_widget.dart): Switch effortlessly between InfiniteList, AnimatedInfiniteList, SliverInfiniteList, AnimatedSliverInfiniteList, InfiniteGrid, and SliverInfiniteGrid via CollectionSettings.
• 🃏 Smart Collection Items: BlocxCollectionItem (stateless) and BlocxStatefulCollectionItem + BlocxCollectionItemState (stateful) with built-in helpers for isSelected, isExpanded, isHighlighted, isBeingRemoved, and modal delete confirmation.
• 🔍 Built-in Search & Scroll-Aware FAB: Drop in searchField() for debounced search and mix in HideOnScrollFabMixin for a FloatingActionButton that hides on scroll-down and reappears on scroll-up.
• 📝 Reactive Form Host & Controls (form_widget.dart): BlocxFormWidgetState automatically manages TextEditingControllers and FocusNodes, hydrates edit-mode data, and provides textField() (with type converter, RTL auto-detection, and async uniqueness spinner), dropdown<T>(), checkbox(), BlocxFormRegisterButton, and BlocxFormButtonRow.
• 🖥️ Unified Screen Management: BlocxScreenManagerState automatically renders BlocxSnackBars, full-screen BlocxErrorWidgets (with stack-trace expansion and retry callbacks), and route pops emitted by any blocx_core BLoC.

Installation #

Add both blocx_core and flutter_blocx to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  blocx_core: ^1.1.0
  flutter_blocx: ^1.1.0

Or run:

flutter pub add blocx_core flutter_blocx

Barrel Imports #

// Full package barrel (Collection widgets, Form widgets, ScreenManager, SnackBar, ErrorWidget, ConfirmAction)
import 'package:flutter_blocx/flutter_blocx.dart';

// Or import modular barrels:
import 'package:flutter_blocx/list_widget.dart';
import 'package:flutter_blocx/form_widget.dart';
import 'package:flutter_blocx/blocx_collection_item_state.dart';

Collection Screens, Lists, Grids & Items #

1. Collection Screen Host (BlocxCollectionWidget & BlocxCollectionWidgetState) #

Extend BlocxCollectionWidget<Payload> and BlocxCollectionWidgetState<W, Entity, Payload> to build any list, grid, or sliver collection screen backed by a BlocxCollectionBloc from blocx_core:

import 'package:blocx_core/collection_bloc.dart';
import 'package:flutter/material.dart';
import 'package:flutter_blocx/flutter_blocx.dart';

class ProductsScreen extends BlocxCollectionWidget<void> {
  const ProductsScreen({super.key});

  @override
  State<ProductsScreen> createState() => _ProductsScreenState();
}

class _ProductsScreenState
    extends BlocxCollectionWidgetState<ProductsScreen, ProductEntity, void>
    with HideOnScrollFabMixin<void> {
  // 1. Required GETTER: instantiate your BlocxCollectionBloc
  @override
  BlocxCollectionBloc<ProductEntity, void> get generateBloc => ProductsBloc();

  // 2. Wrap in a Scaffold with HideOnScrollFabMixin support
  @override
  bool get wrapInScaffold => true;

  @override
  Widget scaffoldWidget(BuildContext context, Widget body) {
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: NotificationListener<UserScrollNotification>(
        onNotification: onScrollNotification,
        child: body,
      ),
      floatingActionButton: getFloatingActionButton(context),
    );
  }

  @override
  void onFabPressed(void data) {
    // Open create product form or dispatch addToList(...)
  }

  // 3. Choose your layout engine (animatedList, list, grid, sliverList, animatedSliverList, sliverGrid)
  @override
  CollectionSettings get settings => CollectionSettings(
        type: CollectionWidgetStateType.grid,
        options: const InfiniteGridOptions(
          crossAxisCount: 2,
          mainAxisSpacing: 12,
          crossAxisSpacing: 12,
          padding: EdgeInsets.all(12),
        ),
      );

  // 4. Optional top widget: built-in debounced searchField()
  @override
  Widget? topWidget(BuildContext context, BlocxCollectionState<ProductEntity> state) {
    return Padding(
      padding: const EdgeInsets.fromLTRB(12, 12, 12, 4),
      child: searchField(
        options: const BlocxSearchFieldOptions(hintText: 'Search products...'),
      ),
    );
  }

  // 5. Optional bottom widget: bulk selection action bar
  @override
  Widget? bottomWidget(BuildContext context, BlocxCollectionState<ProductEntity> state) {
    if (state.selectedCount == 0) return null;
    return Card(
      margin: const EdgeInsets.all(12),
      child: ListTile(
        title: Text('${state.selectedCount} selected'),
        trailing: Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            IconButton(
              icon: const Icon(Icons.deselect),
              onPressed: () => deselectMultipleItems(state.selectedItems),
            ),
            IconButton(
              icon: const Icon(Icons.delete_outline),
              onPressed: () => deleteMultipleItems(state.selectedItems),
            ),
          ],
        ),
      ),
    );
  }

  // 6. Required itemBuilder
  @override
  Widget itemBuilder(BuildContext context, ProductEntity item) {
    return ProductCard(key: ValueKey(item.identifier), item: item);
  }
}

Layout Types & Matching Options (CollectionSettings) #

2. Standalone Composable Views (BlocxCollectionView & BlocxFormView) #

Need to embed a collection list or a form inside a custom layout, tab view, dialog, or multi-pane desktop screen without subclassing BlocxCollectionWidgetState or BlocxFormWidgetState? Use the standalone composable views:

// Standalone collection list view
BlocxCollectionView<ProductEntity, void>(
  bloc: productsBloc,
  itemBuilder: (context, item) => ProductCard(item: item),
  emptyBuilder: (context) => const Center(child: Text('No products available')),
  errorBuilder: (context, error) => BlocxErrorWidget(
    error: error,
    onRetry: () => productsBloc.loadInitialPage(),
  ),
);

// Standalone form view
BlocxFormView<ProfileFormEntity, UserProfileEntity, ProfileFormField>(
  bloc: profileBloc,
  formBuilder: (context, state) => Column(children: [...]),
  loadingBuilder: (context) => const Center(child: CircularProgressIndicator()),
);

3. DI-Friendly BLoC Construction #

BlocxCollectionWidget and BlocxFormWidget support three flexible dependency-injection patterns:

1. Direct constructor injection: Pass bloc: myBloc directly to BlocxCollectionWidget(bloc: myBloc) or BlocxFormWidget(bloc: myBloc).
2. Inherited Provider: Provide the BLoC typed as the base class, e.g. BlocProvider<BlocxCollectionBloc<ProductEntity, void>>.value(...) or BlocProvider<BlocxFormBloc<ProfileForm, User, ProfileField>>.value(...). When generateBloc is not overridden in your state subclass, it automatically resolves context.read<BlocxCollectionBloc<Entity, Payload>>() (or BlocxFormBloc<F, P, E>()). If provided under a concrete subtype, pass it directly via constructor MyWidget(bloc: myBloc) or override get generateBloc => myBloc.
3. Internal instantiation: Subclass and override get generateBloc => MyBloc().

When a BLoC is injected via constructor or context, autoDisposeBloc / autoCloseBloc default to false so ancestor providers retain full lifecycle ownership.

4. Automatic Payload Reload (shouldReloadOnPayloadChange) #

Both BlocxCollectionWidgetState and BlocxFormWidgetState listen for incoming widget updates via didUpdateWidget. When widget.payload changes, reload() is automatically called to refresh the collection or re-initialize the form. To disable automatic reloads upon payload changes, override:

@override
bool get shouldReloadOnPayloadChange => false;

5. Collection Item Widgets (BlocxCollectionItem & BlocxStatefulCollectionItem) #

Stateless Item (BlocxCollectionItem<Entity, Payload>)

class ProductCard extends BlocxCollectionItem<ProductEntity, void> {
  const ProductCard({super.key, required super.item});

  @override
  ConfirmActionOptions get confirmDeleteOptions => ConfirmActionOptions(
        title: 'Delete ${item.name}?',
        question: 'Are you sure you want to permanently remove "${item.name}"?',
      );

  @override
  Widget buildContent(BuildContext context, ProductEntity item) {
    final cs = colorScheme(context);
    final selected = isSelected(context);
    final removing = isBeingRemoved(context);

    return Card(
      color: selected ? cs.primaryContainer : null,
      child: ListTile(
        onTap: () => toggleSelection(context),
        title: Text(item.name),
        subtitle: Text('\$${item.price.toStringAsFixed(2)}'),
        trailing: IconButton(
          icon: removing
              ? const SizedBox.square(
                  dimension: 18,
                  child: CircularProgressIndicator(strokeWidth: 2),
                )
              : Icon(Icons.delete_outline, color: cs.error),
          onPressed: removing ? null : () => removeItem(context),
        ),
      ),
    );
  }
}

Stateful Item (BlocxStatefulCollectionItem<Entity> & BlocxCollectionItemState<W, Entity, Payload>)

When an item needs local State (e.g., an AnimationController or inline TextEditingController), extend BlocxStatefulCollectionItem<T> and BlocxCollectionItemState<W, T, P>. Inside BlocxCollectionItemState, override Widget buildContent(T item) and use context-free getters/methods (isSelected, isExpanded, isBeingRemoved, toggleSelection(), toggleExpansion(), removeItem()).

Form Screens & Reactive Controls #

Form Screen Host (BlocxFormWidget & BlocxFormWidgetState) #

Extend BlocxFormWidget<Payload> and BlocxFormWidgetState<W, FormEntity, Payload, FieldEnum> to connect a BlocxFormBloc from blocx_core to Flutter form controls with automatic controller/focus management:

import 'package:blocx_core/form_bloc.dart';
import 'package:flutter/material.dart';
import 'package:flutter_blocx/flutter_blocx.dart';

class ProfileFormScreen extends BlocxFormWidget<UserProfileEntity> {
  const ProfileFormScreen({super.key, super.payload});

  @override
  State<ProfileFormScreen> createState() => _ProfileFormScreenState();
}

class _ProfileFormScreenState extends BlocxFormWidgetState<
    ProfileFormScreen,
    ProfileFormEntity,
    UserProfileEntity,
    ProfileFormField> {
  // 1. Required GETTER: instantiate your BlocxFormBloc
  @override
  BlocxFormBloc<ProfileFormEntity, UserProfileEntity, ProfileFormField>
      get generateBloc => ProfileFormBloc();

  // 2. Field keys managed by the form
  @override
  List<ProfileFormField> get keys => ProfileFormField.values;

  @override
  bool get wrapInScaffold => true;

  @override
  Widget scaffoldWidget(BuildContext context, Widget body) {
    return Scaffold(
      appBar: AppBar(title: Text(isUpdate ? 'Edit Profile' : 'Create Profile')),
      body: body,
    );
  }

  // 3. Hydrate text controllers in edit mode or on live stream sync
  @override
  void applyInitialDataToForm(ProfileFormEntity formData) {
    getTextEditingController(ProfileFormField.username).text = formData.username;
    getTextEditingController(ProfileFormField.email).text = formData.email;
    getTextEditingController(ProfileFormField.age).text =
        formData.age > 0 ? formData.age.toString() : '';
  }

  // 4. React after successful submission
  @override
  void onFormSubmitted(
    BlocxFormStateFormSubmitted<ProfileFormEntity, ProfileFormField> state,
  ) {
    Navigator.of(context).maybePop(state.submittedData);
  }

  // 5. Build form UI with built-in reactive controls
  @override
  Widget formWidget(
    BuildContext context,
    BlocxFormState<ProfileFormEntity, ProfileFormField> state,
  ) {
    return SingleChildScrollView(
      padding: const EdgeInsets.all(16),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        spacing: formVerticalSpacing,
        children: [
          textField(
            ProfileFormField.username,
            type: TextFieldType.outlined,
            labelText: 'Username',
            prefix: const Icon(Icons.person_outline),
          ),
          textField(
            ProfileFormField.email,
            type: TextFieldType.outlined,
            labelText: 'Email',
            keyboardType: TextInputType.emailAddress,
          ),
          textField(
            ProfileFormField.age,
            type: TextFieldType.outlined,
            labelText: 'Age',
            keyboardType: TextInputType.number,
            converter: (value) => int.tryParse(value) ?? 0,
          ),
          dropdown<String>(
            ProfileFormField.role,
            options: const BlocXDropdownOptions(labelText: 'Role'),
            items: const [
              DropdownMenuItem(value: 'admin', child: Text('Admin')),
              DropdownMenuItem(value: 'member', child: Text('Member')),
            ],
          ),
          checkbox(
            key: ProfileFormField.acceptTerms,
            isChecked: state.formData.acceptTerms,
            options: BlocxCheckboxOptions(
              isChecked: state.formData.acceptTerms,
              label: 'I accept the terms and conditions',
            ),
          ),
          BlocxFormButtonRow<ProfileFormEntity, UserProfileEntity, ProfileFormField>(
            formState: state,
            registerText: isUpdate ? 'Save Changes' : 'Create Profile',
            registerSubmittingText: 'Saving...',
          ),
        ],
      ),
    );
  }
}

Built-in Form Controls #

Form Validation Precedence

flutter_blocx supports two complementary validation mechanisms:

1. BlocX Reactive Validation (Recommended): Configured on the bloc via BlocxFormValidator rules, async uniqueness checks (BlocxUniqueFieldValidatorMixin), and step validation. Errors are reactively streamed into bloc.state.errors and rendered via InputDecoration.errorText.
2. Flutter validator: Hook: An optional standard FormFieldValidator<String> passed to textField(..., validator: ...).

Precedence Rules:

• When Flutter's FormState.validate() runs, any non-null error string returned by Flutter's validator hook takes visual precedence in FormFieldState.
• When the Flutter validator returns null (passes), any active bloc-level error for that field in bloc.state.errors remains rendered on screen.
• Guideline: Place domain validation rules and asynchronous checks in your BlocxFormBloc using pure-Dart BlocxFieldValidator classes. Use Flutter's validator: hook for local UI formatting or when interoperating with third-party form wrappers.

Automatic Focus Management & requestFocusOnError

BlocxFormWidgetState manages FocusNode instances for all fields declared in keys:

• Calling textField(key) or dropdown(key) automatically attaches the managed focus node from getFocusNode(key). You can also supply a custom focusNode: if needed.
• Calling requestFocusOnError(state) focuses the first field with an active error, traversing fields in the declaration order of keys (rather than arbitrary map iteration order).

Screen Management & Shared UX #

1. BlocxScreenManagerState<T> #

Both BlocxCollectionWidgetState and BlocxFormWidgetState extend BlocxScreenManagerState. You can also extend BlocxScreenManagerState<MyScreen> directly on any custom screen to get automatic handling for:

• Snackbars (ScreenManagerCubitStateDisplaySnackbar $\rightarrow$ BlocxSnackBar.show)
• Full-Page Errors (ScreenManagerCubitStateDisplayErrorPage $\rightarrow$ errorWidget(context, state))
• Route Popping (ScreenManagerCubitStatePop $\rightarrow$ Navigator.maybePop())

2. BlocxErrorWidget #

Render Material 3 full-page error cards with collapsible stack traces, copy-to-clipboard, report, and retry actions:

@override
Widget errorWidget(
  BuildContext context,
  ScreenManagerCubitStateDisplayErrorPage state,
) {
  return BlocxErrorWidget.fromState(
    state,
    onRetry: refreshData,
  );
}

3. BlocxSnackBar #

Show themed floating snackbars (BlocxSnackbarType.info, warning, error):

BlocxSnackBar.show(
  context,
  title: 'Saved',
  message: 'Your changes have been saved.',
  type: BlocxSnackbarType.info,
);

4. ConfirmActionWidget #

Display a modal confirmation bottom sheet with optional type-to-confirm protection (requireTyping: true):

final confirmed = await ConfirmActionWidget.show(
  context,
  isScrollControlled: true,
  options: ConfirmActionOptions(
    title: 'Delete Account?',
    question: 'This action is permanent. Type DELETE to confirm.',
    confirmText: 'Delete Forever',
    requireTyping: true,
    deleteWord: 'DELETE',
  ),
);

5. Localization (BlocXLocalizations) #

All built-in labels (loadingText, emptyListText, tryAgain, cancel, delete, and validator messages) come from BlocXLocalizations in blocx_core. Override any string globally before runApp:

void main() {
  BlocXLocalizations.localizations = MyAppLocalizations();
  runApp(const MyApp());
}

Power Your Screens with blocx_core #

flutter_blocx widgets are powered by blocx_core (GitHub). Visit the blocx_core documentation to learn how to build:

• BlocxCollectionBloc with infinite scroll, search, filter, selection, deletion, and live BlocxEventHub synchronization
• BlocxFormBloc with 35+ built-in validators, async uniqueness checks, data prefetching, multi-step wizards, and live form synchronization
• BlocxBaseUseCase & BlocxEventHub for clean domain architecture and automatic cross-BLoC CRUD event broadcasting

👉 Explore blocx_core on pub.flutter-io.cn

Included AI Coding Skill #

This repository includes an AI agent skill at skills/flutter-blocx/SKILL.md (compatible with Claude Code, Antigravity, and Cursor) containing full widget rules, type-signature tables, blueprints, and progressive-disclosure reference guides for flutter_blocx.

Limitations #

1. BLoC Instance Immutability: Dynamically mutating or replacing widget.bloc on an existing widget state is not supported. didUpdateWidget asserts widget.bloc == oldWidget.bloc. To switch BLoCs, re-create the widget subtree or provide the bloc via an ancestor BlocProvider.
2. Inherited Provider Typing: When resolving BLoCs from BuildContext (context.read), the provider must be typed as the base class (BlocProvider<BlocxCollectionBloc<Entity, Payload>> or BlocProvider<BlocxFormBloc<F, P, E>>). If provided under a concrete subtype, pass it directly via constructor MyWidget(bloc: myBloc) or override get generateBloc => myBloc.
3. Sliver Context Requirement: Sliver collection display types (CollectionWidgetStateType.sliverList, sliverGrid, animatedSliverList, animatedSliverGrid) must be placed inside a CustomScrollView or sliver viewport.
4. Form Key Ordering: requestFocusOnError resolves error focus using the declaration order of keys. Ensure your keys getter defines fields in the visual top-to-bottom layout order of your form.

Contributing & License #

Contributions, issues, and feature requests are welcome at the issue tracker.

Released under the MIT License.