{"id":22015615,"url":"https://github.com/iconica-development/flutter_user","last_synced_at":"2025-10-11T13:06:56.787Z","repository":{"id":219909595,"uuid":"748074144","full_name":"Iconica-Development/flutter_user","owner":"Iconica-Development","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-24T14:20:20.000Z","size":172,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-07T01:05:06.986Z","etag":null,"topics":["component","user-story"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Iconica-Development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-25T08:10:38.000Z","updated_at":"2025-04-22T06:50:30.000Z","dependencies_parsed_at":"2024-03-04T11:43:59.767Z","dependency_job_id":"0f356d4a-1629-443e-87a4-98ac7e606f8b","html_url":"https://github.com/Iconica-Development/flutter_user","commit_stats":null,"previous_names":["iconica-development/flutter_auth"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iconica-Development%2Fflutter_user","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iconica-Development%2Fflutter_user/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iconica-Development%2Fflutter_user/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iconica-Development%2Fflutter_user/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Iconica-Development","download_url":"https://codeload.github.com/Iconica-Development/flutter_user/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252793667,"owners_count":21805058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","user-story"],"created_at":"2024-11-30T04:26:44.385Z","updated_at":"2025-10-11T13:06:51.717Z","avatar_url":"https://github.com/Iconica-Development.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flutter_user Documentation\n\n## Overview\n\nflutter_user is a comprehensive Flutter package designed to simplify user authentication flows in your apps. It offers customizable screens and configurations for handling login, registration, password recovery (forgot password), and onboarding processes.\n\nThis package prioritizes flexibility and ease of integration, allowing developers to:\n\n- Quickly incorporate user authentication with minimal setup.\n- Tailor the user experience through extensive customization options.\n\n## Table of Contents\n\n1. Installation\n2. Setup and Initialization\n3. Main Components\n   - FlutterUserNavigatorUserstory\n   - User Repositories\n4. Customization and Configuration\n   - FlutterUserOptions\n   - LoginOptions\n   - ForgotPasswordOptions\n   - RegistrationOptions\n   - Translations\n   - LoginBiometricsOptions\n5. Callbacks and Error Handling\n6. Example Usage\n7. Advanced Customization\n8. Troubleshooting\n9. Contributing\n10. Author\n\n## Installation\n\nTo use flutter_user in your Flutter project, add it as a dependency in your `pubspec.yaml` file:\n\n```yaml\ndependencies:\n  flutter_user:\n    hosted: https://forgejo.internal.iconica.nl/api/packages/internal/pub\n    version: \u003cVersion\u003e\n```\n\nReplace `\u003cVersion\u003e` with the specific version or commit hash you want to use.\n\n## Setup and Initialization\n\n1. Ensure you have the necessary dependencies set up in your project, especially if you're integrating with a backend service like Firebase.\n2. Import the `flutter_user` package in your Dart files:\n\n```dart\nimport 'package:flutter_user/flutter_user.dart';\n```\n\n3. Initialize the `FlutterUserNavigatorUserstory` widget in your app's `MaterialApp` or `CupertinoApp`. This widget manages navigation between the authentication screens:\n\n```dart\nclass MyApp extends StatelessWidget {\n  const MyApp({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      title: \"Flutter User Example\",\n      home: FlutterUserNavigatorUserstory(\n        afterLoginScreen: HomeScreen(),\n        options: FlutterUserOptions(\n          // Custom options go here\n        ),\n      ),\n    );\n  }\n}\n```\n\n## Main Components\n\n**1. FlutterUserNavigatorUserstory**\n\nThis is the core component of flutter_user. It manages navigation between various authentication screens like login, registration, forgot password, and onboarding.\n\n**Key Properties:**\n\n| Property          | Type                    | Description                                        | Default               |\n| ----------------- | ----------------------- | -------------------------------------------------- | --------------------- |\n| afterLoginScreen  | Widget                  | Screen to display after a successful login         | null (required)       |\n| afterRegistration | Widget                  | Screen to display after successful registration    | null                  |\n| userRepository    | UserRepositoryInterface | User repository handling authentication operations | LocalUserRepository() |\n| options           | FlutterUserOptions      | Customization options for the user experience      | FlutterUserOptions()  |\n\n**2. User Repositories**\n\nflutter_user is designed to work with any backend by implementing the `UserRepositoryInterface`. This interface defines the necessary methods for user authentication operations.\n\n**UserRepositoryInterface:**\n\nMethods to implement:\n\n- `Future\u003cLoginResponse\u003e loginWithEmailAndPassword({required String email, required String password});`\n- `Future\u003cRegistrationResponse\u003e register({required Map\u003cString, dynamic\u003e values});`\n- `Future\u003cRequestPasswordResponse\u003e requestChangePassword({required String email});`\n- `Future\u003cbool\u003e logout();`\n- `Future\u003cbool\u003e isLoggedIn();`\n- `Future\u003cdynamic\u003e getLoggedInUser();`\n\n**Default Implementation:**\n\n- `LocalUserRepository`: A mock implementation useful for testing or offline scenarios.\n\n**Example with Firebase:**\n\nTo use Firebase as your backend, implement the `UserRepositoryInterface` using `firebase_auth` and `cloud_firestore`:\n\n```dart\nimport 'package:firebase_auth/firebase_auth.dart';\nimport 'package:cloud_firestore/cloud_firestore.dart';\nimport 'package:user_repository_interface/user_repository_interface.dart';\n\nclass FirebaseUserRepository implements UserRepositoryInterface {\n  final FirebaseAuth _firebaseAuth = FirebaseAuth.instance;\n\n  @override\n  Future\u003cLoginResponse\u003e loginWithEmailAndPassword({required String email, required String password}) {\n    // Implement login logic using Firebase\n  }\n\n  // Implement other methods...\n}\n```\n\n## Customization and Configuration\n\nflutter_user provides extensive customization options to tailor the user interface and behavior to your application's needs.\n\n### FlutterUserOptions\n\nThe `FlutterUserOptions` class centralizes customization for the user authentication flow.\n\n**Properties:**\n\n| Property              | Type                            | Description                                            | Default                   |\n| --------------------- | ------------------------------- | ------------------------------------------------------ | ------------------------- |\n| loginOptions          | `LoginOptions`                  | Customization options for the login screen             | `LoginOptions()`          |\n| forgotPasswordOptions | `ForgotPasswordOptions`         | Customization options for the forgot password screen   | `ForgotPasswordOptions()` |\n| registrationOptions   | `RegistrationOptions`           | Customization options for the registration screen      | `RegistrationOptions()`   |\n| beforeLogin           | `Future\u003cvoid\u003e Function()`       | Callback before login attempt                          | `null`                    |\n| afterLogin            | `Future\u003cvoid\u003e Function()`       | Callback after successful login                        | `null`                    |\n| onRegister            | `Future\u003cvoid\u003e Function()`       | Callback after registration is completed               | `null`                    |\n| useOnboarding         | `bool`                          | Whether to use the onboarding process                  | `false`                   |\n| onOnboardingComplete  | `Future\u003cvoid\u003e Function()`       | Callback after onboarding is completed                 | `null`                    |\n| onForgotPassword      | `Future\u003cvoid\u003e Function(String)` | Callback when the forgot password process is initiated | `null`                    |\n\n### LoginOptions\n\nCustomize the login screen's appearance and behavior.\n\n**Key Properties:**\n\n- `initialEmail`: Pre-fill the email input field. (String)\n- `initialPassword`: Pre-fill the password input field. (String)\n- `emailDecoration`: Input decoration for the email field. (InputDecoration)\n- `passwordDecoration`: Input decoration for the password field. (InputDecoration)\n- `emailTextAlign`: Text alignment for the email field. (TextAlign)\n- `passwordTextAlign`: Text alignment for the password field. (TextAlign)\n- `loginButtonBuilder`: Custom builder for the login button. (Widget Function(BuildContext context, VoidCallback onPressed, bool disabled, VoidCallback onDisabledPress, FlutterUserOptions options))\n- `forgotPasswordButtonBuilder`: Custom builder for the forgot password button. (Widget Function(BuildContext context, VoidCallback onPressed))\n- `registrationButtonBuilder`: Custom builder for the registration button. (Widget Function(BuildContext context, VoidCallback onPressed))\n- `image`: Widget to display an image or logo on the login screen. (Widget)\n- `spacers`: `LoginSpacerOptions` to adjust spacing between elements. (LoginSpacerOptions)\n- `biometricsOptions`: `LoginBiometricsOptions` to configure biometric login options. (LoginBiometricsOptions)\n\n### LoginBiometricsOptions\n\nCustomize biometric login options.\n\nYou can use faceID or fingerprint by adding:\n```dart\n  loginWithBiometrics: true,\n  triggerBiometricsAutomatically: true,\n```\nto the `LoginOptions` object. This will trigger the biometrics authentication immediately when the EmailPasswordLoginForm is shown.\n\nFor the full biometrics setup you can follow the instructions in the [local_auth](https://pub.dev/packages/local_auth) package. \n\nYou need to add the following permissions to your AndroidManifest.xml file:\n\n```xml\n  \u003cuses-permission android:name=\"android.permission.USE_BIOMETRIC\"/\u003e\n```\n\n```java\nimport io.flutter.embedding.android.FlutterFragmentActivity;\n\npublic class MainActivity extends FlutterFragmentActivity {\n    // ...\n}\n```\n\nor MainActivity.kt:\n\n```kotlin\nimport io.flutter.embedding.android.FlutterFragmentActivity\n\nclass MainActivity: FlutterFragmentActivity() {\n    // ...\n}\n```\n\nto inherit from `FlutterFragmentActivity`.\n\n### ForgotPasswordOptions\n\nCustomize the forgot password screen's appearance and behavior.\n\n**Key Properties:**\n\n- `forgotPasswordBackgroundColor`: Background color of the screen. (Color)\n- `forgotPasswordCustomAppBar`: Custom app bar widget. (Widget)\n- `forgotPasswordScreenPadding`: Padding for the screen content. (EdgeInsets)\n- `forgotPasswordSpacerOptions`: Adjust spacing using `ForgotPasswordSpacerOptions`. (ForgotPasswordSpacerOptions)\n- `translations`: Provide custom text via `ForgotPasswordTranslations`. (ForgotPasswordTranslations)\n- `requestForgotPasswordButtonBuilder`: Custom builder for the reset password button. (Widget Function(BuildContext context, VoidCallback onPressed))\n\n### RegistrationOptions\n\nCustomize the registration process.\n\n**Key Properties:**\n\n- `steps`: Define multi-step registration fields. (List\u003cRegistrationStep\u003e)\n- `translations`: Provide custom text via `RegistrationTranslations`. (RegistrationTranslations)\n- `customAppbarBuilder`: Custom app bar for the registration screen. (Widget Function(BuildContext context))\n- `title`: Widget for the registration screen title. (Widget)\n- `spacerOptions`: Adjust spacing using `RegistrationSpacerOptions`. (RegistrationSpacerOptions)\n- `previousButtonBuilder`: Custom builder for the “Previous” button. (Widget Function(BuildContext context, VoidCallback onPressed))\n- `nextButtonBuilder`: Custom builder for the “Next” button. (Widget Function(BuildContext context, VoidCallback onPressed))\n- `loginButton`: Widget to navigate back to the login screen. (Widget)\n\n### Translations\n\nLocalization support is provided through translation classes:\n\n- `LoginTranslations`: Customize text for login screens.\n- `ForgotPasswordTranslations`: Customize text for forgot password screens.\n- `RegistrationTranslations`: Customize text for registration screens.\n\n## Callbacks and Error Handling\n\n### Callbacks\n\nflutter_user provides various callbacks to gracefully handle user actions and errors.\n\n| Callback                        | Description                                                 |\n| ------------------------------- | ----------------------------------------------------------- |\n| `beforeLogin`                   | Called before the login attempt is made.                    |\n| `afterLogin`                    | Called after a successful login.                            |\n| `onRegister`                    | Called after the registration process is completed.         |\n| `onForgotPassword`              | Called when the user initiates the forgot password process. |\n| `onRequestForgotPassword`       | Called after the forgot password request is completed.      |\n| `onForgotPasswordSuccess`       | Called after a successful password reset request.           |\n| `onForgotPasswordUnsuccessful`  | Called when the password reset request fails.               |\n| `onRegistrationError`           | Called when registration fails.                             |\n| `afterRegistration`             | Called after the registration process.                      |\n| `afterRegistrationSuccess`      | Called after successful registration.                       |\n| `afterRegistrationUnsuccessful` | Called when registration is unsuccessful.                   |\n\n### Error Handling\n\n- **Validation Errors:**\n\n  - Utilize the built-in `LoginValidationService` or `RegistrationValidationService` for validation.\n  - Alternatively, provide custom validators for specific needs.\n\n- **Repository Errors:**\n  - Implement proper error handling in your user repository classes.\n  - Utilize the provided `UserError` model for consistent error reporting.\n\n## Example Usage\n\nThis example demonstrates setting up `flutter_user` with custom options and integrating it into your app.\n\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:flutter_user/flutter_user.dart';\nimport 'package:user_repository_interface/user_repository_interface.dart';\n\nvoid main() {\n  runApp(const MyApp());\n}\n\nclass MyApp extends StatelessWidget {\n  const MyApp({super.key});\n\n  // Define your home screen after login\n  Widget get homeScreen =\u003e const HomeScreen();\n\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp(\n      title: 'Flutter User Example',\n      theme: ThemeData(\n        primarySwatch: Colors.blue,\n      ),\n      home: FlutterUserNavigatorUserstory(\n        afterLoginScreen: homeScreen,\n        options: FlutterUserOptions(\n          loginOptions: LoginOptions(\n            initialEmail: 'user@example.com',\n            emailDecoration: const InputDecoration(\n              labelText: 'Email',\n            ),\n            passwordDecoration: const InputDecoration(\n              labelText: 'Password',\n            ),\n            image: Image.asset('assets/logo.png'),\n          ),\n          registrationOptions: RegistrationOptions(\n            steps: [\n              // Add more steps if necessary\n            ],\n          ),\n          afterLogin: () async {\n            // Navigate to a different screen or perform other actions\n          },\n          useOnboarding: true,\n        ),\n      ),\n    );\n  }\n}\n\nclass HomeScreen extends StatelessWidget {\n  const HomeScreen({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      // Your home screen content\n    );\n  }\n}\n```\n\n## Advanced Customization\n\n### Custom Widgets and Builders\n\nFor more control over UI components, provide custom widgets and builders in the options classes.\n\n**Example: Custom Login Button Builder**\n\n```dart\nloginOptions: LoginOptions(\n  loginButtonBuilder: (context, onPressed, disabled, onDisabledPress, options) {\n    return ElevatedButton(\n      onPressed: disabled ? null : onPressed,\n      child: Text('Sign In'),\n    );\n  },\n)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n- **Firebase Setup:** Ensure Firebase is correctly configured in your Flutter app. Refer to the official Firebase Flutter setup guide for instructions.\n- **Dependency Conflicts:** Check for version conflicts between dependencies, especially between `firebase_auth` and `cloud_firestore`.\n- **Validation Errors:** If custom validation isn't working as expected, verify that your custom validation service is correctly implemented and assigned in the `LoginOptions`.\n\n### Tips\n\n- **Logging:** Utilize Flutter's debugging tools and print statements to trace issues during development.\n- **Error Messages:** Pay close attention to error messages returned by the user repository. These messages can help identify and resolve issues promptly.\n\n## Contributing\n\nWe welcome contributions to improve `flutter_user`, whether it's enhancing documentation, fixing bugs, or adding new features. Please follow the Contribution Guide and submit your pull requests on GitHub.\n\n## Author\n\nflutter_user is developed and maintained by Iconica. For questions, support, or commercial inquiries, please contact them at support@iconica.nl.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficonica-development%2Fflutter_user","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficonica-development%2Fflutter_user","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficonica-development%2Fflutter_user/lists"}