DEV Community: Manish Mali

Flutter: The Ultimate Production-Ready SharedPreferences Wrapper

Manish Mali — Sun, 07 Dec 2025 03:15:33 +0000

As Flutter developers, we use shared_preferences in almost every app. However, calling SharedPreferences.getInstance() repeatedly, handling JSON parsing manually, or managing key strings can quickly become messy.

In this article, I am sharing a Production-Grade Wrapper Class that I use in enterprise applications. It handles:

✅ Singleton Pattern: Guaranteed single instance

✅ Reactive State: Listen to login state changes automatically

✅ Data Migration: Handle version updates without losing user data

✅ Type Safety: Methods for Colors, Dates, Enums, and Objects

✅ Crash Proofing: Safe getters that never throw null errors

📦 Installation

First, add the package to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^2.5.3

💻 The Complete Implementation

Copy this entire file into your project (e.g., services/prefs_service.dart).

import 'dart:async';
import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

class Prefs {
  // ========================================================================
  // 1. SINGLETON PATTERN IMPLEMENTATION (ROBUST)
  // ========================================================================

  static Prefs? _instance;
  static SharedPreferences? _preferences;
  static Completer<Prefs>? _initCompleter;

  Prefs._();

  /// Call this in main() before runApp: await Prefs.getInstance();
  static Future<Prefs> getInstance() async {
    if (_instance != null) return _instance!;

    if (_initCompleter != null) {
      return _initCompleter!.future;
    }

    _initCompleter = Completer<Prefs>();

    try {
      final service = Prefs._();
      await service._initialize();
      _instance = service;
      _initCompleter!.complete(_instance);
      return _instance!;
    } catch (e, st) {
      debugPrint('🛑 Prefs Initialization Error: $e\n$st');
      if (!(_initCompleter?.isCompleted ?? true)) {
        _initCompleter!.completeError(e, st);
      }
      rethrow;
    }
  }

  Future<void> _initialize() async {
    try {
      _preferences = await SharedPreferences.getInstance();
      await _checkMigration();

      // Initialize reactive listener with saved value
      authNotifier.value = _getBool(_PreferenceKeys.isUserSignIn);
    } catch (e) {
      debugPrint('🛑 SharedPreferences initialization error: $e');
      rethrow;
    }
  }

  static bool _isReady() => _preferences != null;

  static void _warnIfNotInitialized(String methodName) {
    if (!_isReady()) {
      debugPrint(
        '⚠️ Prefs: You called $methodName before Prefs.getInstance() finished. This may lead to fallback/default values.',
      );
    }
  }

  // ========================================================================
  // 2. DATA MIGRATION (VERSION CONTROL)
  // ========================================================================

  Future<void> _checkMigration() async {
    const int currentVersion = 1;
    const String versionKey = 'prefs_version';

    int savedVersion = _getInt(versionKey, defaultValue: 0);

    if (savedVersion < currentVersion) {
      debugPrint(
        "🔄 Migrating Prefs from v$savedVersion to v$currentVersion...",
      );
      // --- MIGRATION LOGIC HERE ---
      // Example: await remove('old_unused_key');
      await _setInt(versionKey, currentVersion);
    }
  }

  // ========================================================================
  // 3. REACTIVE LISTENERS
  // ========================================================================
  static final ValueNotifier<bool> authNotifier = ValueNotifier<bool>(false);

  // ========================================================================
  // 4. APP SPECIFIC GETTERS & SETTERS (Variables)
  // ========================================================================

  static bool get isUserSignIn {
    _warnIfNotInitialized('isUserSignIn');
    return _getBool(_PreferenceKeys.isUserSignIn);
  }

  static Future<bool> setIsUserSignIn(bool value) async {
    _warnIfNotInitialized('setIsUserSignIn');
    final res = await _setBool(_PreferenceKeys.isUserSignIn, value);
    authNotifier.value = value;
    return res;
  }

  static String get yourEmail {
    _warnIfNotInitialized('yourEmail');
    return _getString(_PreferenceKeys.yourEmail);
  }

  static Future<bool> setYourEmail(String value) async {
    _warnIfNotInitialized('setYourEmail');
    return await _setString(_PreferenceKeys.yourEmail, value);
  }

  static String get yourName {
    _warnIfNotInitialized('yourName');
    return _getString(_PreferenceKeys.yourName);
  }

  static Future<bool> setYourName(String value) async {
    _warnIfNotInitialized('setYourName');
    return await _setString(_PreferenceKeys.yourName, value);
  }

  static String get yourId {
    _warnIfNotInitialized('yourId');
    return _getString(_PreferenceKeys.yourId);
  }

  static Future<bool> setYourId(String value) async {
    _warnIfNotInitialized('setYourId');
    return await _setString(_PreferenceKeys.yourId, value);
  }

  // ========================================================================
  // 5. SMART LOGOUT (PARTIAL CLEAR)
  // ========================================================================

  static Future<void> clearUserData() async {
    _warnIfNotInitialized('clearUserData');
    debugPrint('🧹 Clearing User Data...');
    await remove(_PreferenceKeys.isUserSignIn);
    await remove(_PreferenceKeys.yourEmail);
    await remove(_PreferenceKeys.yourName);
    await remove(_PreferenceKeys.yourId);
    authNotifier.value = false;
  }

  static Future<void> clearAllExcept(List<String> keysToKeep) async {
    _warnIfNotInitialized('clearAllExcept');
    final Set<String> allKeys = getAllKeys();
    for (String key in allKeys) {
      if (!keysToKeep.contains(key)) {
        await remove(key);
      }
    }
  }

  // ========================================================================
  // 6. COLOR HANDLING & OBFUSCATION
  // ========================================================================

  /// Save a Color object (Stores as 32-bit ARGB int)
  static Future<bool> setColor(String key, Color color) async {
    _warnIfNotInitialized('setColor');
    final int packed = _tryToARGB32(color);
    return await (_preferences?.setInt(key, packed) ?? Future.value(false));
  }

  static int _tryToARGB32(Color c) {
    try {
      return c.toARGB32();
    } catch (_) {
      return c.value;
    }
  }

  /// Get a Color object safely
  static Color getColor(String key, Color defaultColor) {
    _warnIfNotInitialized('getColor');

    try {
      final int? stored = _preferences?.getInt(key);
      if (stored == null) return defaultColor;

      final a = (stored >> 24) & 0xFF;
      final r = (stored >> 16) & 0xFF;
      final g = (stored >> 8) & 0xFF;
      final b = stored & 0xFF;

      return Color.fromARGB(a, r, g, b);
    } catch (_) {
      return defaultColor;
    }
  }

  static Future<bool> setObfuscatedString(String key, String value) async {
    _warnIfNotInitialized('setObfuscatedString');
    String encoded = base64Encode(utf8.encode(value));
    return await _setString(key, encoded);
  }

  static String getObfuscatedString(String key) {
    _warnIfNotInitialized('getObfuscatedString');
    String encoded = _getString(key);
    if (encoded.isEmpty) return '';
    try {
      return utf8.decode(base64Decode(encoded));
    } catch (e) {
      return '';
    }
  }

  // ========================================================================
  // 7. GENERIC OBJECT & MODEL STORAGE
  // ========================================================================

  static Future<bool> setObject<T>(
    String key,
    T value,
    Map<String, dynamic> Function(T) toJson,
  ) async {
    _warnIfNotInitialized('setObject');
    return await _preferences?.setString(key, jsonEncode(toJson(value))) ??
        false;
  }

  static T? getObject<T>(
    String key,
    T Function(Map<String, dynamic>) fromJson,
  ) {
    _warnIfNotInitialized('getObject');

    final jsonString = _preferences?.getString(key);
    if (jsonString == null || jsonString.isEmpty) return null;

    try {
      final Map<String, dynamic> m =
          jsonDecode(jsonString) as Map<String, dynamic>;
      return fromJson(m);
    } catch (e) {
      debugPrint("Prefs parsing error for key '$key': $e");
      return null;
    }
  }

  // ========================================================================
  // 8. LIST OF OBJECTS / JSON LIST
  // ========================================================================

  static Future<bool> setJsonList(
    String key,
    List<Map<String, dynamic>> list,
  ) async {
    _warnIfNotInitialized('setJsonList');
    final List<String> jsonStringList = list
        .map((item) => jsonEncode(item))
        .toList();
    return await (_preferences?.setStringList(key, jsonStringList) ?? false);
  }

  static List<Map<String, dynamic>> getJsonList(String key) {
    _warnIfNotInitialized('getJsonList');
    final List<String>? jsonStringList = _preferences?.getStringList(key);
    if (jsonStringList == null) return [];
    return jsonStringList.map((item) {
      try {
        return jsonDecode(item) as Map<String, dynamic>;
      } catch (_) {
        return <String, dynamic>{};
      }
    }).toList();
  }

  // ========================================================================
  // 9. STRING LIST & HISTORY
  // ========================================================================

  static List<String> getStringList(String key) {
    _warnIfNotInitialized('getStringList');
    return _preferences?.getStringList(key) ?? [];
  }

  static Future<bool> setStringList(String key, List<String> value) async {
    _warnIfNotInitialized('setStringList');
    return await _preferences?.setStringList(key, value) ?? false;
  }

  static Future<void> addToStringListUnique(String key, String value) async {
    _warnIfNotInitialized('addToStringListUnique');
    final List<String> list = getStringList(key);
    if (list.contains(value)) list.remove(value);
    list.add(value);
    await setStringList(key, list);
  }

  // ========================================================================
  // 10. LOGIC HELPERS
  // ========================================================================

  static Future<void> toggleBool(String key) async {
    _warnIfNotInitialized('toggleBool');
    bool current = _getBool(key);
    await _setBool(key, !current);
  }

  /// Returns true only on FIRST call
  static bool isFirstTime(String key) {
    _warnIfNotInitialized('isFirstTime');
    final bool? isFirst = _preferences?.getBool(key);
    if (isFirst == null || isFirst == true) {
      _preferences?.setBool(key, false);
      return true;
    }
    return false;
  }

  // ========================================================================
  // 11. DEBUGGING TOOLS
  // ========================================================================

  static void debugDumpAll() {
    _warnIfNotInitialized('debugDumpAll');
    debugPrint('--- 📦 PREFS STORAGE DUMP 📦 ---');
    final keys = getAllKeys();
    if (keys.isEmpty) {
      debugPrint('Storage is Empty');
    } else {
      for (String key in keys) {
        debugPrint('$key: ${_preferences?.get(key)}');
      }
    }
    debugPrint('--------------------------------');
  }

  // ========================================================================
  // 12. ADVANCED UTILITY METHODS (EXTRAS)
  // ========================================================================

  static Future<bool> setJson(String key, Map<String, dynamic> jsonMap) async {
    _warnIfNotInitialized('setJson');
    return await _preferences?.setString(key, jsonEncode(jsonMap)) ?? false;
  }

  static Map<String, dynamic>? getJson(String key) {
    _warnIfNotInitialized('getJson');
    try {
      final jsonString = _preferences?.getString(key);
      if (jsonString == null || jsonString.isEmpty) return null;
      final decoded = jsonDecode(jsonString);
      return decoded is Map<String, dynamic> ? decoded : null;
    } catch (_) {
      return null;
    }
  }

  static Future<bool> setDate(String key, DateTime date) async {
    _warnIfNotInitialized('setDate');
    return await _setString(key, date.toIso8601String());
  }

  static DateTime? getDate(String key) {
    _warnIfNotInitialized('getDate');
    final String dateStr = _getString(key);
    return dateStr.isNotEmpty ? DateTime.tryParse(dateStr) : null;
  }

  static Future<bool> setEnum<T extends Enum>(String key, T value) async {
    _warnIfNotInitialized('setEnum');
    return await _setString(key, value.name);
  }

  static T getEnum<T extends Enum>(String key, List<T> values, T defaultValue) {
    _warnIfNotInitialized('getEnum');
    String name = _getString(key);
    return values.firstWhere((e) => e.name == name, orElse: () => defaultValue);
  }

  /// Flash Data: get once and delete
  static String? getAndRemoveString(String key) {
    _warnIfNotInitialized('getAndRemoveString');
    final String value = _getString(key);
    if (value.isNotEmpty) {
      remove(key);
      return value;
    }
    return null;
  }

  static Future<void> incrementInt(String key, {int amount = 1}) async {
    _warnIfNotInitialized('incrementInt');
    await _setInt(key, _getInt(key) + amount);
  }

  // ========================================================================
  // 13. DYNAMIC & INT LIST HELPERS
  // ========================================================================

  static Future<bool> setDynamicList(String key, List<dynamic> list) async {
    _warnIfNotInitialized('setDynamicList');
    return await _setJsonString(key, list);
  }

  static List<dynamic> getDynamicList(String key) {
    _warnIfNotInitialized('getDynamicList');
    return _getJsonAsList(key) ?? [];
  }

  static Future<bool> updateDynamicListItem(
    String key,
    int index,
    dynamic newValue,
  ) async {
    _warnIfNotInitialized('updateDynamicListItem');
    final list = getDynamicList(key).toList();

    if (index < 0) return false;

    if (index >= list.length) {
      list.length = index + 1;
      for (int i = 0; i < list.length; i++) {
        if (i >= list.length) break;
        if (list[i] == null) list[i] = list[i];
      }
    }

    list[index] = newValue;
    return await setDynamicList(key, list);
  }

  static Future<bool> removeDynamicListIndex(String key, int index) async {
    _warnIfNotInitialized('removeDynamicListIndex');
    final list = getDynamicList(key).toList();
    if (index < 0 || index >= list.length) return false;
    list.removeAt(index);
    return await setDynamicList(key, list);
  }

  static Future<bool> setIntList(String key, List<int> list) async {
    _warnIfNotInitialized('setIntList');
    final safe = list.map((e) => e).toList();
    return await _setJsonString(key, safe);
  }

  static List<int> getIntList(String key) {
    _warnIfNotInitialized('getIntList');
    final List<dynamic>? raw = _getJsonAsList(key);
    if (raw == null) return [];
    try {
      return raw
          .map((e) => (e is int) ? e : int.tryParse(e.toString()) ?? 0)
          .toList();
    } catch (_) {
      return [];
    }
  }

  static Future<bool> updateIntListIndex(
    String key,
    int index,
    int newValue,
  ) async {
    _warnIfNotInitialized('updateIntListIndex');
    final list = getIntList(key).toList();
    if (index < 0) return false;
    if (index >= list.length) {
      final required = index + 1 - list.length;
      list.addAll(List<int>.filled(required, 0));
    }
    list[index] = newValue;
    return await setIntList(key, list);
  }

  static Future<bool> removeIntListIndex(String key, int index) async {
    _warnIfNotInitialized('removeIntListIndex');
    final list = getIntList(key).toList();
    if (index < 0 || index >= list.length) return false;
    list.removeAt(index);
    return await setIntList(key, list);
  }

  // ========================================================================
  // 14. MAP STORAGE & NESTED LIST OPERATIONS
  // ========================================================================

  static Future<bool> setMap(String key, Map<String, dynamic> map) async {
    _warnIfNotInitialized('setMap');
    return await _setString(key, jsonEncode(map));
  }

  static Map<String, dynamic> getMap(String key) {
    _warnIfNotInitialized('getMap');
    try {
      final raw = _preferences?.getString(key);
      if (raw == null || raw.isEmpty) return {};
      final decoded = jsonDecode(raw);
      return decoded is Map<String, dynamic> ? decoded : {};
    } catch (_) {
      return {};
    }
  }

  static Future<bool> _updateListInMap(
    String key,
    String mapKey,
    int index,
    dynamic newValue, {
    bool extendWithNulls = true,
    bool fillIntWithZero = false,
  }) async {
    _warnIfNotInitialized('_updateListInMap');
    final map = getMap(key);
    final rawList = map[mapKey];

    if (rawList is List) {
      final List<dynamic> list = List<dynamic>.from(rawList);
      if (index < 0) return false;

      if (index >= list.length) {
        if (extendWithNulls) {
          final required = index + 1 - list.length;
          if (fillIntWithZero) {
            list.addAll(List<dynamic>.filled(required, 0));
          } else {
            list.addAll(List<dynamic>.filled(required, null));
          }
        } else {
          return false;
        }
      }

      list[index] = newValue;
      map[mapKey] = list;
      return await setMap(key, map);
    } else {
      if (index < 0) return false;
      final List<dynamic> newList = List<dynamic>.filled(index + 1, null);
      newList[index] = newValue;
      map[mapKey] = newList;
      return await setMap(key, map);
    }
  }

  static Future<bool> _removeIndexInMap(
    String key,
    String mapKey,
    int index,
  ) async {
    _warnIfNotInitialized('_removeIndexInMap');
    final map = getMap(key);
    final rawList = map[mapKey];
    if (rawList is List) {
      final List<dynamic> list = List<dynamic>.from(rawList);
      if (index < 0 || index >= list.length) return false;
      list.removeAt(index);
      map[mapKey] = list;
      return await setMap(key, map);
    }
    return false;
  }

  static Future<bool> updateMapNumberIndex(
    String key,
    int listIndex,
    int newValue,
  ) async {
    _warnIfNotInitialized('updateMapNumberIndex');
    return await _updateListInMap(
      key,
      'numbers',
      listIndex,
      newValue,
      extendWithNulls: true,
      fillIntWithZero: true,
    );
  }

  static Future<bool> updateMapStringIndex(
    String key,
    int listIndex,
    String newValue,
  ) async {
    _warnIfNotInitialized('updateMapStringIndex');
    return await _updateListInMap(
      key,
      'strings',
      listIndex,
      newValue,
      extendWithNulls: true,
      fillIntWithZero: false,
    );
  }

  static Future<bool> deleteMapNumberIndex(String key, int listIndex) async {
    _warnIfNotInitialized('deleteMapNumberIndex');
    return await _removeIndexInMap(key, 'numbers', listIndex);
  }

  static Future<bool> deleteMapStringIndex(String key, int listIndex) async {
    _warnIfNotInitialized('deleteMapStringIndex');
    return await _removeIndexInMap(key, 'strings', listIndex);
  }

  // ========================================================================
  // 15. CUSTOM USER MODEL STORAGE SECTION
  // ========================================================================

  static Future<bool> setUser(User user) async {
    _warnIfNotInitialized('setUser');
    return await _setString("user_data", jsonEncode(user.toJson()));
  }

  static User? getUser() {
    _warnIfNotInitialized('getUser');
    final raw = _getString("user_data");
    if (raw.isEmpty) return null;
    try {
      return User.fromJson(jsonDecode(raw));
    } catch (_) {
      return null;
    }
  }

  static Future<bool> updateUserName(String newName) async {
    final user = getUser();
    if (user == null) return false;

    user.name = newName;
    return await setUser(user);
  }

  static Future<bool> updateUserAge(int newAge) async {
    final user = getUser();
    if (user == null) return false;

    user.age = newAge;
    return await setUser(user);
  }

  static Future<bool> updateUserBank({
    String? bankName,
    String? accountNumber,
  }) async {
    final user = getUser();
    if (user == null) return false;

    user.bank = Bank(
      bankName ?? user.bank.bankName,
      accountNumber ?? user.bank.accountNumber,
    );

    return await setUser(user);
  }

  static Future<bool> updateUserNumberAt(int index, int newValue) async {
    final user = getUser();
    if (user == null) return false;

    if (index < 0) return false;

    if (index >= user.numbers.length) {
      final int needed = index - user.numbers.length + 1;
      user.numbers.addAll(List.filled(needed, 0));
    }

    user.numbers[index] = newValue;
    return await setUser(user);
  }

  static Future<bool> removeUserNumberAt(int index) async {
    final user = getUser();
    if (user == null) return false;

    if (index < 0 || index >= user.numbers.length) return false;

    user.numbers.removeAt(index);
    return await setUser(user);
  }

  static Future<bool> addUserNumber(int value) async {
    final user = getUser();
    if (user == null) return false;

    user.numbers.add(value);
    return await setUser(user);
  }

  // ========================================================================
  // 16. CRASH-PROOF PRIVATE HELPERS (SAFE GETTERS)
  // ========================================================================

  static bool _getBool(String key, {bool defaultValue = false}) {
    try {
      return _preferences?.getBool(key) ?? defaultValue;
    } catch (e) {
      return defaultValue;
    }
  }

  static Future<bool> _setBool(String key, bool value) async {
    try {
      return await (_preferences?.setBool(key, value) ?? Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to set bool $key -> $e');
      return false;
    }
  }

  static String _getString(String key, {String defaultValue = ''}) {
    try {
      return _preferences?.getString(key) ?? defaultValue;
    } catch (e) {
      return _preferences?.get(key)?.toString() ?? defaultValue;
    }
  }

  static Future<bool> _setString(String key, String value) async {
    try {
      return await (_preferences?.setString(key, value) ?? Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to set string $key -> $e');
      return false;
    }
  }

  static int _getInt(String key, {int defaultValue = 0}) {
    try {
      return _preferences?.getInt(key) ?? defaultValue;
    } catch (e) {
      final val = _preferences?.get(key);
      if (val is String) return int.tryParse(val) ?? defaultValue;
      return defaultValue;
    }
  }

  static Future<bool> _setInt(String key, int value) async {
    try {
      return await (_preferences?.setInt(key, value) ?? Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to set int $key -> $e');
      return false;
    }
  }

  static double _getDouble(String key, {double defaultValue = 0.0}) {
    try {
      return _preferences?.getDouble(key) ?? defaultValue;
    } catch (e) {
      final val = _preferences?.get(key);
      if (val is String) return double.tryParse(val) ?? defaultValue;
      if (val is int) return val.toDouble();
      return defaultValue;
    }
  }

  static Future<bool> _setDouble(String key, double value) async {
    try {
      return await (_preferences?.setDouble(key, value) ?? Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to set double $key -> $e');
      return false;
    }
  }

  static List<String> _getStringList(
    String key, {
    List<String> defaultValue = const [],
  }) {
    try {
      return _preferences?.getStringList(key) ?? defaultValue;
    } catch (e) {
      return defaultValue;
    }
  }

  static Future<bool> _setStringList(String key, List<String> value) async {
    try {
      return await (_preferences?.setStringList(key, value) ??
          Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to set stringList $key -> $e');
      return false;
    }
  }

  // ========================================================================
  // 17. MANAGEMENT
  // ========================================================================

  static Future<bool> clearAll() async {
    _warnIfNotInitialized('clearAll');
    return await (_preferences?.clear() ?? Future.value(false));
  }

  static Future<bool> remove(String key) async {
    _warnIfNotInitialized('remove');
    return await (_preferences?.remove(key) ?? Future.value(false));
  }

  static bool containsKey(String key) {
    _warnIfNotInitialized('containsKey');
    return _preferences?.containsKey(key) ?? false;
  }

  static Set<String> getAllKeys() {
    _warnIfNotInitialized('getAllKeys');
    return _preferences?.getKeys() ?? {};
  }

  Future<void> reload() async {
    _warnIfNotInitialized('reload');
    await _preferences?.reload();
  }

  // ========================================================================
  // Private: JSON helpers used by lists & maps
  // ========================================================================

  static Future<bool> _setJsonString(String key, Object value) async {
    try {
      final encoded = jsonEncode(value);
      return await (_preferences?.setString(key, encoded) ??
          Future.value(false));
    } catch (e) {
      debugPrint('Prefs: Failed to _setJsonString $key -> $e');
      return false;
    }
  }

  static List<dynamic>? _getJsonAsList(String key) {
    try {
      final raw = _preferences?.getString(key);
      if (raw == null || raw.isEmpty) return null;
      final decoded = jsonDecode(raw);
      if (decoded is List) return decoded;
      return null;
    } catch (e) {
      debugPrint('Prefs: Failed to _getJsonAsList $key -> $e');
      return null;
    }
  }
}

// ========================================================================
// KEYS CONSTANTS
// ========================================================================

class _PreferenceKeys {
  static const String isUserSignIn = 'isUserSignIn';
  static const String yourEmail = 'yourEmail';
  static const String yourName = 'yourName';
  static const String yourId = 'yourId';
}

// ========================================================================
// MODELS
// ========================================================================

class User {
  String name;
  int age;
  List<int> numbers;
  Bank bank;

  User(this.name, this.age, this.numbers, this.bank);

  Map<String, dynamic> toJson() => {
        'name': name,
        'age': age,
        'numbers': numbers,
        'bank': bank.toJson(),
      };

  factory User.fromJson(Map<String, dynamic> json) => User(
        json['name'],
        json['age'],
        List<int>.from(json['numbers']),
        Bank.fromJson(json['bank']),
      );
}

class Bank {
  String bankName;
  String accountNumber;

  Bank(this.bankName, this.accountNumber);

  Map<String, dynamic> toJson() => {
        'bankName': bankName,
        'accountNumber': accountNumber,
      };

  factory Bank.fromJson(Map<String, dynamic> json) => Bank(
        json['bankName'],
        json['accountNumber'],
      );
}

🚀 Usage Examples

Step 1: Initialization

Call this in your main.dart before running the app:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 🚀 Initialize Prefs once
  await Prefs.getInstance();

  runApp(const MyApp());
}

Step 2: Basic Getters & Setters

// Setting data
await Prefs.setYourName("John Doe");
await Prefs.setYourEmail("john@example.com");

// Getting data (No await needed!)
String name = Prefs.yourName;
print("User Name: $name");

Step 3: Reactive State (Listener)

No complex state management needed:

// In your UI, listen to auth changes
ValueListenableBuilder<bool>(
  valueListenable: Prefs.authNotifier,
  builder: (context, isLoggedIn, child) {
    return isLoggedIn ? HomePage() : LoginPage();
  },
);

// Updating triggers UI rebuild automatically
await Prefs.setIsUserSignIn(true);

Step 4: Storing Colors & Encrypted Data

// 🎨 Save a Theme Color
await Prefs.setColor('theme_color', Colors.deepPurple);
Color myColor = Prefs.getColor('theme_color', Colors.blue);

// 🔒 Save Sensitive Data (Base64 Obfuscated)
await Prefs.setObfuscatedString('api_key', 'super_secret_123');
String apiKey = Prefs.getObfuscatedString('api_key');

Step 5: Storing Custom Objects

class User {
  String name;
  int age;

  Map<String, dynamic> toJson() => {'name': name, 'age': age};
  static User fromJson(Map<String, dynamic> json) => 
      User(json['name'], json['age']);
}

// Save Object
User user = User("Alice", 25);
await Prefs.setObject('current_user', user, (u) => u.toJson());

// Get Object
User? savedUser = Prefs.getObject(
  'current_user', 
  (json) => User.fromJson(json)
);

Step 6: Lists & Search History

// Save search term
await Prefs.addToStringListUnique('search_history', 'Flutter Tutorial');

// Get list
List<String> history = Prefs.getStringList('search_history');

Step 7: Advanced Dynamic Lists

Update specific indexes without overwriting:

// Initial: [10, 20, 30]
await Prefs.setIntList('scores', [10, 20, 30]);

// Update index 1 → [10, 99, 30]
await Prefs.updateIntListIndex('scores', 1, 99);

// Auto-extend: Update index 5 → [10, 99, 30, 0, 0, 50]
await Prefs.updateIntListIndex('scores', 5, 50);

// Remove index 0 → [99, 30, 0, 0, 50]
await Prefs.removeIntListIndex('scores', 0);

Step 8: Complex Maps & Nested Lists

// Map: { "strings": ["A", "B"] }
await Prefs.setMap('config', {'strings': ['A', 'B']});

// Update nested list → { "strings": ["A", "C"] }
await Prefs.updateMapStringIndex('config', 1, "C");

Step 9: Utilities (Date, Enums, First Time)

// 📅 Date Storage
await Prefs.setDate('last_login', DateTime.now());
DateTime? lastLogin = Prefs.getDate('last_login');

// 🔠 Enum Storage
enum ThemeMode { light, dark }
await Prefs.setEnum('theme_mode', ThemeMode.dark);
ThemeMode mode = Prefs.getEnum(
  'theme_mode', 
  ThemeMode.values, 
  ThemeMode.light
);

// 🆕 First Time Check (true only once)
if (Prefs.isFirstTime('show_intro')) {
  showIntroDialog();
}

// Toggle Settings
await Prefs.toggleBool('notifications_enabled');

Step 10: User Model with Nested Updates

// Create user
User newUser = User(
  "Alex", 
  30, 
  [100, 200], 
  Bank("HDFC", "1234567890")
);
await Prefs.setUser(newUser);

// Update only bank name
await Prefs.updateUserBank(bankName: "ICICI");

// Update both fields
await Prefs.updateUserBank(
  bankName: "SBI", 
  accountNumber: "0987654321"
);

// Modify number list
await Prefs.addUserNumber(500);
await Prefs.updateUserNumberAt(1, 999);  // [100, 999]
await Prefs.removeUserNumberAt(0);       // [999]

// Safe auto-padding
await Prefs.updateUserNumberAt(10, 50);  // Auto-fills with 0s

// Update other fields
await Prefs.updateUserName("Alexander");
await Prefs.updateUserAge(31);

// Retrieve
User? currentUser = Prefs.getUser();
if (currentUser != null) {
  print(currentUser.bank.bankName);  // "SBI"
  print(currentUser.numbers);        // [999, ...]
}

Step 11: Logout & Debugging

// Clear user data only
await Prefs.clearUserData();

// Clear all except specific keys
await Prefs.clearAllExcept(['intro_shown', 'theme']);

// 🐛 Debug dump
Prefs.debugDumpAll();

🎯 Key Features Breakdown

1️⃣ Singleton Pattern

Thread-safe initialization with Completer
Prevents multiple instances
Warns if accessed before initialization

2️⃣ Data Migration

Built-in version control system
Seamless upgrades without data loss
Easy to extend for future versions

3️⃣ Reactive Listeners

ValueNotifier for auth state
No need for complex state management
Automatic UI updates

4️⃣ Type Safety

Dedicated methods for all data types
Compile-time checking
Zero runtime type errors

5️⃣ Crash Proofing

Safe getters with default values
Try-catch wrapped operations
Never throws null pointer exceptions

6️⃣ Advanced Operations

Update list items by index
Nested map manipulations
Auto-extending lists
Partial object updates

📊 Performance Benefits

Operation	Traditional Way	This Wrapper
Initialization	Multiple getInstance() calls	Single initialization
Type Safety	Manual casting	Built-in type methods
Error Handling	Manual try-catch	Automatic safe getters
Code Lines	15-20 per operation	1-2 per operation
Null Safety	Manual checks	Built-in defaults

🛡️ Production-Ready Features

✅ Migration Ready: Version control built-in

✅ Crash Proof: Safe getters never throw

✅ Memory Efficient: Singleton pattern

✅ Type Safe: Compile-time checking

✅ Reactive: ValueNotifier integration

✅ Debuggable: Built-in dump tools

✅ Flexible: Supports complex data structures

✅ Clean Code: Minimal boilerplate

💡 Best Practices

Initialize Early: Always call Prefs.getInstance() in main()
Use Type-Safe Methods: Prefer setColor() over generic setInt()
Handle Nulls: Always provide default values for getters
Use Reactive Listeners: Leverage authNotifier for state changes
Debug Regularly: Use debugDumpAll() during development
Plan Migration: Update version number when changing data structure

🔧 Customization

To add your own keys, update the _PreferenceKeys class:

class _PreferenceKeys {
  static const String isUserSignIn = 'isUserSignIn';
  static const String yourEmail = 'yourEmail';
  static const String yourName = 'yourName';
  static const String yourId = 'yourId';

  // Add your custom keys
  static const String customKey = 'custom_key';
}

Then add corresponding getters/setters:

static String get customValue {
  _warnIfNotInitialized('customValue');
  return _getString(_PreferenceKeys.customKey);
}

static Future<bool> setCustomValue(String value) async {
  _warnIfNotInitialized('setCustomValue');
  return await _setString(_PreferenceKeys.customKey, value);
}

🎓 Conclusion

This Prefs wrapper eliminates boilerplate, ensures type safety, and provides production-grade reliability. By implementing:

✅ Singleton pattern for consistency
✅ Reactive state for UI updates
✅ Migration system for data integrity
✅ Type-safe methods for all data types
✅ Crash-proof operations

You get a robust, maintainable, and scalable solution for data persistence in Flutter.

📬 Get Help

If you need assistance implementing this wrapper or want the complete code:

💬 Comment below and I'll respond with the full implementation

📧 Message me directly for custom modifications

⭐ Follow for more Flutter utilities and best practices

Happy Coding! 🚀

Found this helpful? Drop a ❤️ reaction and share with your Flutter community!

Tags: #Flutter #Dart #MobileDevelopment #SharedPreferences #StateManagement #CleanCode #BestPractices

Complete Guide: Pagination in Flutter with 4 State Management Approaches (StatefulWidget, GetX, Provider & BLoC)

Manish Mali — Wed, 03 Dec 2025 18:15:55 +0000

🚀 Complete Guide: Pagination in Flutter with 4 State Management Approaches

📖 Introduction

Pagination is a crucial feature in modern mobile applications. When dealing with large datasets, loading all data at once can:

❌ Consume excessive memory
❌ Slow down your app
❌ Provide poor user experience
❌ Waste network bandwidth

In this comprehensive guide, we'll implement pagination with infinite scroll and pull-to-refresh using 4 different state management approaches in Flutter:

StatefulWidget - Traditional approach using setState()
GetX - Reactive and lightweight
Provider - Google's recommended approach
BLoC - Event-driven architecture for large apps

✨ What We'll Build

A Flutter app that displays 100 users with:

📜 Infinite Scroll: Auto-loads more data when scrolling to bottom
🔄 Pull-to-Refresh: Swipe down to refresh
🔘 Manual Refresh Button: Tap to refresh
⚠️ Error Handling: Retry on failures
💾 10 Users Per Page: Simulates API pagination

🛠️ Project Setup

1. Create Flutter Project

flutter create pagination_demo
cd pagination_demo

2. Add Dependencies

Update your pubspec.yaml:

name: pagination
description: "A Flutter pagination demo with multiple state management approaches"
publish_to: 'none'
version: 0.1.0

environment:
  sdk: ^3.9.2

dependencies:
  flutter:
    sdk: flutter
  provider: ^6.1.2        # Provider state management
  flutter_bloc: ^8.1.6    # BLoC pattern
  equatable: ^2.0.7       # Value equality for BLoC
  get: ^4.6.6             # GetX state management

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true

3. Install Dependencies

flutter pub get

📦 Common Files (Models & Data)

These files are shared across all implementations.

User Model (`lib/models/user_model.dart`)

/// User Model Class
/// Represents a user with basic information
class UserModel {
  /// Unique identifier for the user
  final int id;

  /// User's full name
  final String name;

  /// User's email address
  final String email;

  /// Constructor for UserModel
  UserModel({required this.id, required this.name, required this.email});

  /// Factory constructor to create UserModel from JSON
  factory UserModel.fromJson(Map<String, dynamic> json) {
    return UserModel(
      id: json['id'] as int,
      name: json['name'] as String,
      email: json['email'] as String,
    );
  }

  /// Converts UserModel to JSON
  Map<String, dynamic> toJson() {
    return {'id': id, 'name': name, 'email': email};
  }

  /// Creates a copy with updated values
  UserModel copyWith({int? id, String? name, String? email}) {
    return UserModel(
      id: id ?? this.id,
      name: name ?? this.name,
      email: email ?? this.email,
    );
  }

  @override
  String toString() => 'UserModel(id: $id, name: $name, email: $email)';

  @override
  bool operator ==(Object other) {
    if (identical(this, other)) return true;
    return other is UserModel &&
        other.id == id &&
        other.name == name &&
        other.email == email;
  }

  @override
  int get hashCode => id.hashCode ^ name.hashCode ^ email.hashCode;
}

Dummy Data Provider (`lib/common/dummy_data.dart`)

This simulates API responses with network delays.

import '../models/user_model.dart';

/// DummyData Class
/// Simulates API responses with paginated user data
class DummyData {
  /// Total users available
  static const int totalUsers = 100;

  /// Users per page
  static const int usersPerPage = 10;

  /// Private constructor
  DummyData._();

  /// Generate dummy users
  static List<UserModel> _generateAllUsers() {
    return List.generate(totalUsers, (index) {
      final userId = index + 1;
      return UserModel(
        id: userId,
        name: 'User ${userId.toString().padLeft(3, '0')}',
        email: 'user$userId@example.com',
      );
    });
  }

  /// Cached users list
  static final List<UserModel> _allUsers = _generateAllUsers();

  /// Fetch paginated users (simulates API call)
  static Future<List<UserModel>> fetchUsers({
    required int page,
    int pageSize = usersPerPage,
  }) async {
    // Simulate network delay (1-2 seconds)
    await Future.delayed(Duration(milliseconds: 1000 + (page % 2) * 1000));

    final startIndex = (page - 1) * pageSize;
    final endIndex = startIndex + pageSize;

    if (startIndex >= _allUsers.length) return [];

    return _allUsers.sublist(
      startIndex,
      endIndex > _allUsers.length ? _allUsers.length : endIndex,
    );
  }

  /// Check if more data is available
  static bool hasMoreData({required int currentPage, int pageSize = usersPerPage}) {
    return currentPage < (totalUsers / pageSize).ceil();
  }

  /// Refresh data (returns first page)
  static Future<List<UserModel>> refreshData({int pageSize = usersPerPage}) async {
    await Future.delayed(const Duration(milliseconds: 1500));
    return fetchUsers(page: 1, pageSize: pageSize);
  }

  /// Get all users
  static List<UserModel> getAllUsers() => List.from(_allUsers);
}

1️⃣ StatefulWidget Implementation

📖 What is StatefulWidget?

StatefulWidget is Flutter's built-in way to manage state. It uses setState() to trigger UI rebuilds.

Pros:

✅ No external packages needed
✅ Simple and straightforward
✅ Perfect for small widgets

Cons:

❌ Can become messy in large apps
❌ Logic mixed with UI
❌ Harder to test

📝 Complete Code

lib/screens/stateful_pagination_screen.dart:

import 'package:flutter/material.dart';
import '../common/dummy_data.dart';
import '../models/user_model.dart';

/// StatefulPaginationScreen
/// Demonstrates pagination using StatefulWidget and setState()
class StatefulPaginationScreen extends StatefulWidget {
  const StatefulPaginationScreen({super.key});

  @override
  State<StatefulPaginationScreen> createState() =>
      _StatefulPaginationScreenState();
}

class _StatefulPaginationScreenState extends State<StatefulPaginationScreen> {
  // ==================== State Variables ====================
  List<UserModel> _users = [];
  int _currentPage = 1;
  bool _isLoading = false;
  bool _hasMoreData = true;
  bool _hasError = false;
  String _errorMessage = '';
  final ScrollController _scrollController = ScrollController();

  // ==================== Lifecycle Methods ====================
  @override
  void initState() {
    super.initState();
    _loadInitialData();
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    _scrollController.removeListener(_onScroll);
    _scrollController.dispose();
    super.dispose();
  }

  // ==================== Data Loading Methods ====================

  /// Load initial data
  Future<void> _loadInitialData() async {
    setState(() {
      _isLoading = true;
      _hasError = false;
      _errorMessage = '';
      _currentPage = 1;
    });

    try {
      final users = await DummyData.fetchUsers(page: _currentPage);

      setState(() {
        _users = users;
        _hasMoreData = DummyData.hasMoreData(currentPage: _currentPage);
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
        _hasError = true;
        _errorMessage = 'Failed to load data: $e';
      });
    }
  }

  /// Load more data (pagination)
  Future<void> _loadMoreData() async {
    if (_isLoading || !_hasMoreData) return;

    setState(() {
      _isLoading = true;
      _hasError = false;
    });

    try {
      final nextPage = _currentPage + 1;
      final newUsers = await DummyData.fetchUsers(page: nextPage);

      setState(() {
        _currentPage = nextPage;
        _users.addAll(newUsers);
        _hasMoreData = DummyData.hasMoreData(currentPage: _currentPage);
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
        _hasError = true;
        _errorMessage = 'Failed to load more data: $e';
      });
    }
  }

  /// Refresh data
  Future<void> _refreshData() async {
    setState(() {
      _hasError = false;
      _errorMessage = '';
    });

    try {
      final users = await DummyData.refreshData();

      setState(() {
        _users = users;
        _currentPage = 1;
        _hasMoreData = DummyData.hasMoreData(currentPage: 1);
      });
    } catch (e) {
      setState(() {
        _hasError = true;
        _errorMessage = 'Failed to refresh data: $e';
      });
    }
  }

  /// Scroll listener
  void _onScroll() {
    if (_scrollController.position.pixels >=
        _scrollController.position.maxScrollExtent * 0.8) {
      _loadMoreData();
    }
  }

  // ==================== UI Builder Methods ====================
  @override
  Widget build(BuildContext context) {
    return Scaffold(appBar: _buildAppBar(), body: _buildBody());
  }

  PreferredSizeWidget _buildAppBar() {
    return AppBar(
      title: const Text('Stateful Pagination'),
      centerTitle: true,
      actions: [
        IconButton(
          icon: const Icon(Icons.refresh),
          onPressed: _isLoading ? null : _refreshData,
          tooltip: 'Refresh',
        ),
      ],
    );
  }

  Widget _buildBody() {
    return RefreshIndicator(onRefresh: _refreshData, child: _buildContent());
  }

  Widget _buildContent() {
    if (_isLoading && _users.isEmpty) {
      return const Center(child: CircularProgressIndicator());
    }

    if (_hasError && _users.isEmpty) {
      return _buildErrorView();
    }

    return _buildUserList();
  }

  Widget _buildErrorView() {
    return Center(
      child: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Icon(Icons.error_outline, size: 64, color: Colors.red),
            const SizedBox(height: 16),
            Text(_errorMessage, textAlign: TextAlign.center),
            const SizedBox(height: 16),
            ElevatedButton.icon(
              onPressed: _loadInitialData,
              icon: const Icon(Icons.refresh),
              label: const Text('Retry'),
            ),
          ],
        ),
      ),
    );
  }

  Widget _buildUserList() {
    return ListView.builder(
      controller: _scrollController,
      padding: const EdgeInsets.all(8.0),
      itemCount: _users.length + (_hasMoreData ? 1 : 0),
      itemBuilder: (context, index) {
        if (index == _users.length) {
          return const Padding(
            padding: EdgeInsets.all(16.0),
            child: Center(child: CircularProgressIndicator()),
          );
        }
        return _buildUserCard(_users[index]);
      },
    );
  }

  Widget _buildUserCard(UserModel user) {
    return Card(
      margin: const EdgeInsets.symmetric(horizontal: 8.0, vertical: 4.0),
      child: ListTile(
        leading: CircleAvatar(
          child: Text(user.id.toString(),
              style: const TextStyle(fontWeight: FontWeight.bold)),
        ),
        title: Text(user.name, style: const TextStyle(fontWeight: FontWeight.w600)),
        subtitle: Text(user.email),
        trailing: const Icon(Icons.arrow_forward_ios, size: 16),
      ),
    );
  }
}

🎯 Key Concepts

setState(): Triggers UI rebuild
ScrollController: Detects scroll position for pagination
RefreshIndicator: Enables pull-to-refresh
State Variables: All managed within the State class

🚀 Main File for StatefulWidget

import 'package:flutter/material.dart';
import 'screens/stateful_pagination_screen.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'StatefulWidget Pagination',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: const StatefulPaginationScreen(),
    );
  }
}

2️⃣ GetX Implementation

📖 What is GetX?

GetX is a lightweight and powerful state management solution with minimal boilerplate.

Pros:

✅ Very simple syntax
✅ Minimal boilerplate
✅ Built-in routing, dialogs, snackbars
✅ Reactive programming with .obs

Cons:

❌ Learning curve for reactive programming
❌ Can be "too magical" for some developers

📝 Complete Code

Controller (`lib/controllers/user_controller.dart`)

import 'package:get/get.dart';
import '../common/dummy_data.dart';
import '../models/user_model.dart';

/// UserController for GetX
/// Manages pagination state using reactive variables
class UserController extends GetxController {
  // Reactive state variables
  final RxList<UserModel> users = <UserModel>[].obs;
  final RxInt currentPage = 1.obs;
  final RxBool isLoading = false.obs;
  final RxBool isLoadingMore = false.obs;
  final RxBool hasMoreData = true.obs;
  final RxBool hasError = false.obs;
  final RxString errorMessage = ''.obs;

  // Computed properties
  int get userCount => users.length;
  bool get isEmpty => users.isEmpty;

  @override
  void onInit() {
    super.onInit();
    loadInitialData();
  }

  /// Load initial data
  Future<void> loadInitialData() async {
    isLoading.value = true;
    hasError.value = false;
    errorMessage.value = '';
    currentPage.value = 1;

    try {
      final fetchedUsers = await DummyData.fetchUsers(page: currentPage.value);
      users.value = fetchedUsers;
      hasMoreData.value = DummyData.hasMoreData(currentPage: currentPage.value);
      isLoading.value = false;
    } catch (e) {
      isLoading.value = false;
      hasError.value = true;
      errorMessage.value = 'Failed to load data: $e';
      Get.snackbar('Error', 'Failed to load data: $e',
          snackPosition: SnackPosition.BOTTOM);
    }
  }

  /// Load more data
  Future<void> loadMoreData() async {
    if (isLoadingMore.value || !hasMoreData.value) return;

    isLoadingMore.value = true;

    try {
      final nextPage = currentPage.value + 1;
      final newUsers = await DummyData.fetchUsers(page: nextPage);

      currentPage.value = nextPage;
      users.addAll(newUsers);
      hasMoreData.value = DummyData.hasMoreData(currentPage: currentPage.value);
      isLoadingMore.value = false;
    } catch (e) {
      isLoadingMore.value = false;
      Get.snackbar('Error', 'Failed to load more: $e',
          snackPosition: SnackPosition.BOTTOM);
    }
  }

  /// Refresh data
  Future<void> refreshData() async {
    try {
      final fetchedUsers = await DummyData.refreshData();
      users.value = fetchedUsers;
      currentPage.value = 1;
      hasMoreData.value = DummyData.hasMoreData(currentPage: 1);
    } catch (e) {
      Get.snackbar('Error', 'Failed to refresh: $e',
          snackPosition: SnackPosition.BOTTOM);
    }
  }
}

UI Screen (`lib/screens/getx_pagination_screen.dart`)

import 'package:flutter/material.dart';
import 'package:get/get.dart';
import '../controllers/user_controller.dart';
import '../models/user_model.dart';

/// GetX Pagination Screen
/// Uses Obx() for reactive UI updates
class GetxPaginationScreen extends StatelessWidget {
  const GetxPaginationScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final controller = Get.put(UserController());

    return Scaffold(
      appBar: _buildAppBar(controller),
      body: _buildBody(controller),
    );
  }

  PreferredSizeWidget _buildAppBar(UserController controller) {
    return AppBar(
      title: const Text('GetX Pagination'),
      centerTitle: true,
      actions: [
        Obx(() {
          return IconButton(
            icon: const Icon(Icons.refresh),
            onPressed:
                controller.isLoading.value ? null : () => controller.refreshData(),
            tooltip: 'Refresh',
          );
        }),
      ],
    );
  }

  Widget _buildBody(UserController controller) {
    return RefreshIndicator(
      onRefresh: () => controller.refreshData(),
      child: Obx(() => _buildContent(controller)),
    );
  }

  Widget _buildContent(UserController controller) {
    if (controller.isLoading.value && controller.isEmpty) {
      return const Center(child: CircularProgressIndicator());
    }

    if (controller.hasError.value && controller.isEmpty) {
      return _buildErrorView(controller);
    }

    return _buildUserList(controller);
  }

  Widget _buildErrorView(UserController controller) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          const Icon(Icons.error_outline, size: 64, color: Colors.red),
          const SizedBox(height: 16),
          Text(controller.errorMessage.value),
          const SizedBox(height: 16),
          ElevatedButton.icon(
            onPressed: () => controller.loadInitialData(),
            icon: const Icon(Icons.refresh),
            label: const Text('Retry'),
          ),
        ],
      ),
    );
  }

  Widget _buildUserList(UserController controller) {
    return NotificationListener<ScrollNotification>(
      onNotification: (scrollInfo) {
        if (scrollInfo.metrics.pixels >=
            scrollInfo.metrics.maxScrollExtent * 0.8) {
          if (!controller.isLoadingMore.value && controller.hasMoreData.value) {
            controller.loadMoreData();
          }
        }
        return false;
      },
      child: Obx(() {
        return ListView.builder(
          padding: const EdgeInsets.all(8.0),
          itemCount:
              controller.users.length + (controller.hasMoreData.value ? 1 : 0),
          itemBuilder: (context, index) {
            if (index == controller.users.length) {
              return const Padding(
                padding: EdgeInsets.all(16.0),
                child: Center(child: CircularProgressIndicator()),
              );
            }
            return _buildUserCard(controller.users[index]);
          },
        );
      }),
    );
  }

  Widget _buildUserCard(UserModel user) {
    return Card(
      margin: const EdgeInsets.symmetric(horizontal: 8.0, vertical: 4.0),
      child: ListTile(
        leading: CircleAvatar(
          child: Text(user.id.toString(),
              style: const TextStyle(fontWeight: FontWeight.bold)),
        ),
        title: Text(user.name, style: const TextStyle(fontWeight: FontWeight.w600)),
        subtitle: Text(user.email),
        trailing: const Icon(Icons.arrow_forward_ios, size: 16),
      ),
    );
  }
}

🎯 Key Concepts

.obs: Makes variables reactive
Obx(): Rebuilds widget when reactive variables change
Get.put(): Dependency injection
Get.snackbar(): Easy snackbar notifications

🚀 Main File for GetX

import 'package:flutter/material.dart';
import 'screens/getx_pagination_screen.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'GetX Pagination',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.green),
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: const GetxPaginationScreen(),
    );
  }
}

Full Provider and BLoC implementations are provided in the complete source code. Due to length, this article focuses on StatefulWidget and GetX. Visit the GitHub repository for complete code of all 4 implementations.

📊 Comparison & When to Use What

Quick Comparison Table

Feature	StatefulWidget	GetX	Provider	BLoC
Learning Curve	Easy	Easy-Medium	Medium	Hard
Boilerplate	Low	Very Low	Medium	High
Testability	Medium	Good	Good	Excellent
Performance	Good	Good	Good	Excellent
Setup Complexity	Low	Low	Medium	High
Code Lines	~350	~300	~320	~450
Best For	Small Widgets	Quick Apps	Production Apps	Enterprise Apps
Package Size	0 KB (Built-in)	95 KB	15 KB	140 KB

When to Use Each Approach

🔵 Use StatefulWidget When:

✅ Building simple widgets with local state
✅ You don't want external dependencies
✅ State is only needed in one widget
✅ Learning Flutter basics
✅ Quick prototypes

🟢 Use GetX When:

✅ You want minimal boilerplate
✅ Building apps quickly
✅ Need routing, dialogs, and snackbars
✅ Prefer reactive programming
✅ Small to medium-sized apps
✅ Rapid development needed

🔵 Use Provider When:

✅ Following Google's recommendations
✅ Need good documentation
✅ Building production apps
✅ Want balance between simplicity and scalability
✅ Medium to large-sized apps
✅ Team collaboration

🟣 Use BLoC When:

✅ Building enterprise-level apps
✅ Need high testability
✅ Multiple developers working on same codebase
✅ Predictable state management is critical
✅ Large, complex apps
✅ Strict separation of concerns

💻 Complete Source Code

Project Structure

lib/
├── models/
│   └── user_model.dart              # User data model
├── common/
│   └── dummy_data.dart              # Dummy data provider
├── screens/
│   ├── stateful_pagination_screen.dart    # StatefulWidget version
│   ├── getx_pagination_screen.dart        # GetX version
│   ├── provider_pagination_screen.dart    # Provider version
│   └── bloc_pagination_screen.dart        # BLoC version
├── controllers/
│   └── user_controller.dart         # GetX controller
├── providers/
│   └── user_provider.dart           # Provider class
├── bloc/
│   ├── user_event.dart              # BLoC events
│   ├── user_state.dart              # BLoC states
│   └── user_bloc.dart               # BLoC logic
└── main.dart                        # Main app with navigation

GitHub Repository

git clone https://github.com/manishmali816026/flutter-pagination-demo
cd flutter-pagination-demo
flutter pub get
flutter run

🎯 Conclusion

Congratulations! 🎉 You now have 4 production-ready pagination implementations in Flutter!

What You Learned:

✅ Pagination Fundamentals

Infinite scroll implementation
Pull-to-refresh functionality
Network delay simulation
Error handling patterns

✅ State Management Mastery

StatefulWidget with setState()
GetX with reactive programming
Provider with ChangeNotifier
BLoC with event-driven architecture

✅ Best Practices

Scroll position detection
Loading state management
User experience optimization
Code organization

Key Takeaways:

StatefulWidget - Perfect for simple cases, zero dependencies
GetX - Fastest development time, minimal boilerplate
Provider - Google-recommended, production-ready
BLoC - Most structured, enterprise-grade

Choose Based On:

Your Need	Best Choice
Learning Flutter	StatefulWidget
MVP/Prototype	GetX
Production App	Provider
Large Enterprise	BLoC
Small Widget	StatefulWidget
Medium App	GetX or Provider
High Testability	BLoC

Next Steps:

🔥 Enhance Your Implementation:

Add search and filter functionality
Implement data caching with Hive
Connect to real REST APIs
Add unit and widget tests
Implement sorting features
Add skeleton loading screens

🔥 Advanced Topics:

Offline-first architecture
GraphQL pagination
Firebase Firestore pagination
Complex filtering systems
Performance optimization
Memory management

📚 Additional Resources

Official Documentation:

🙏 Thank You!

Thank you for reading this comprehensive guide! If you found it helpful:

Show Your Support:

❤️ React to this article
💬 Comment with your questions or feedback
🔖 Bookmark for future reference
🔄 Share with fellow Flutter developers
⭐ Star the GitHub repository

Join the Discussion:

Which state management do you prefer?
Have you used pagination in production?
What challenges have you faced?
Any tips to share with the community?

Connect With Me:

💻 GitHub: @manishmali816026
💼 LinkedIn: Manish Mali

📢 More Flutter Content

Want more Flutter tutorials? Follow me for:

State Management Deep Dives
Flutter Architecture Patterns
Performance Optimization Tips
Real-world App Development
Flutter Tips & Tricks

Happy Coding! Keep Building Amazing Flutter Apps! 🚀

Tags for Discovery:

flutter #dart #statemanagement #pagination #getx #provider #bloc #mobiledev #programming #tutorial #flutterdev #coding #softwaredevelopment #appdevelopment #tech

Article Last Updated: January 2025
Written with ❤️ for the Flutter Community

DEV Community: Manish Mali

Flutter: The Ultimate Production-Ready SharedPreferences Wrapper

📦 Installation

💻 The Complete Implementation

🚀 Usage Examples

Step 1: Initialization

Step 2: Basic Getters & Setters

Step 3: Reactive State (Listener)

Step 4: Storing Colors & Encrypted Data

Step 5: Storing Custom Objects

Step 6: Lists & Search History

Step 7: Advanced Dynamic Lists

Step 8: Complex Maps & Nested Lists

Step 9: Utilities (Date, Enums, First Time)

Step 10: User Model with Nested Updates

Step 11: Logout & Debugging

🎯 Key Features Breakdown

1️⃣ Singleton Pattern

2️⃣ Data Migration

3️⃣ Reactive Listeners

4️⃣ Type Safety

5️⃣ Crash Proofing

6️⃣ Advanced Operations

📊 Performance Benefits

🛡️ Production-Ready Features

💡 Best Practices

🔧 Customization

🎓 Conclusion

📬 Get Help

Complete Guide: Pagination in Flutter with 4 State Management Approaches (StatefulWidget, GetX, Provider & BLoC)

🚀 Complete Guide: Pagination in Flutter with 4 State Management Approaches

📖 Introduction

✨ What We'll Build

🛠️ Project Setup

1. Create Flutter Project

2. Add Dependencies

3. Install Dependencies

📦 Common Files (Models & Data)

User Model (lib/models/user_model.dart)

Dummy Data Provider (lib/common/dummy_data.dart)

1️⃣ StatefulWidget Implementation

📖 What is StatefulWidget?

📝 Complete Code

🎯 Key Concepts

🚀 Main File for StatefulWidget

2️⃣ GetX Implementation

📖 What is GetX?

📝 Complete Code

Controller (lib/controllers/user_controller.dart)

UI Screen (lib/screens/getx_pagination_screen.dart)

🎯 Key Concepts

🚀 Main File for GetX

📊 Comparison & When to Use What

Quick Comparison Table

When to Use Each Approach

🔵 Use StatefulWidget When:

🟢 Use GetX When:

🔵 Use Provider When:

🟣 Use BLoC When:

💻 Complete Source Code

Project Structure

GitHub Repository

🎯 Conclusion

What You Learned:

Key Takeaways:

Choose Based On:

Next Steps:

📚 Additional Resources

Official Documentation:

Recommended Reading:

🙏 Thank You!

Show Your Support:

Join the Discussion:

Connect With Me:

📢 More Flutter Content

Tags for Discovery:

flutter #dart #statemanagement #pagination #getx #provider #bloc #mobiledev #programming #tutorial #flutterdev #coding #softwaredevelopment #appdevelopment #tech

User Model (`lib/models/user_model.dart`)

Dummy Data Provider (`lib/common/dummy_data.dart`)

Controller (`lib/controllers/user_controller.dart`)

UI Screen (`lib/screens/getx_pagination_screen.dart`)