flutter_gb_ui_kit

A comprehensive, production-ready Flutter UI Kit and design system tailored for modern mobile applications. Built on top of Flutter Material 3, flutter_gb_ui_kit provides robust theming, smart async buttons, accessible form controls, smooth micro-animations, and reusable turnkey screen templates.

🚀 Key Features

  • 🎨 Modern Material 3 Theming: Factory helper (createGBTheme) generating a unified ThemeData across color schemes, typography, radiuses, and component themes.
  • ⚡ Smart Asynchronous Buttons: ContainedButton, OutlinedButton, and LinkButton subclassing standard Material 3 buttons with built-in debounced loading states (busy).
  • 📝 Form Inputs & Selects: Rich input suite featuring TextField with custom validation feedback checklists, PasswordField with visibility toggle, 4/6-digit CodeField (PIN/OTP), SelectField (Bottom Sheet & Overlay modes), MultiSelectField with chips, and Switcher.
  • ✨ Micro-Animations & Shimmers: MusicVisualizer frequency waves, AnimatedPlaceholder skeleton shimmers, AnimatedFadeHeightSwitcher accordion toggles, and AnimatedDisplayable.
  • 📜 Dynamic Lists & Slivers: AnimatableStateListView for auto-diffing smooth item insertions and deletions, and SliverFooter for pinning footers in CustomScrollViews.
  • 💬 Modals & Snackbars: Accessible dialogs (showAppModal) and floating alerts (showSnackBarAlert).
  • 🛠️ Utility Components: ScreenLoadingIndicator, Stepper, TimePicker with slot constraints, GenericDataHandlerWidget (loading/error/retry), and TimerCountDownBuilder.
  • 📱 Production Screen Templates: Turnkey authentication screens including Login, Sign Up, Password Recovery, Code Verification, and Loading/Error state views.

📖 Table of Contents

  1. Installation
  2. Quick Start & Theming
  3. Component Showcases
  4. Screen Templates
  5. Running the Example App
  6. Migration Guide

Installation

Add flutter_gb_ui_kit to your project's pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_gb_ui_kit:
    path: ../gb-ui-kit # or your git/pub dependency

Then run:

flutter pub get

Quick Start & Theming

flutter_gb_ui_kit leverages standard Flutter ThemeData via createGBTheme(). Wrap your app root with OverlayCanvas to support overlay-mode dropdowns and popups.

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

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

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

  @override
  Widget build(BuildContext context) {
    // Generate a cohesive Material 3 theme
    final theme = createGBTheme(
      primary: const Color(0xFF2563EB),
      secondary: const Color(0xFFF59E0B),
      background: Colors.white,
      surface: Colors.white,
      borderRadius: BorderRadius.circular(12),
      isDark: false,
    );

    return MaterialApp(
      title: 'My App',
      theme: theme,
      builder: (context, child) => OverlayCanvas(
        child: child ?? const SizedBox.shrink(),
      ),
      home: const HomeScreen(),
    );
  }
}

Component Showcases

Buttons & Actions

Buttons inherit your ThemeData styling and provide automatic spinner debounce handling when asynchronous tasks are executing:

// Large Primary Button with built-in busy indicator
ContainedButton.large(
  text: 'Submit Application',
  busy: _isSubmitting,
  onPressed: _handleSubmit,
);

// Gradient Button
ContainedButton.large(
  text: 'Upgrade to Pro',
  gradient: const GBButtonGradient(
    colors: [Color(0xFF2563EB), Color(0xFF7C3AED)],
  ),
  onPressed: _handleUpgrade,
);

// Outlined Button
OutlinedButton.small(
  text: 'Cancel',
  onPressed: () => Navigator.pop(context),
);

// Inline Action Link Text
ComposedActionText(
  normalText: 'Don’t have an account? ',
  actionText: 'Sign Up',
  onAction: () => navigateToSignUp(),
);

Form Fields & Inputs

// Text Field with icon and helper
TextField(
  label: 'Email Address',
  hintText: 'name@company.com',
  prefixIcon: const Icon(Icons.email_outlined),
  errorText: _hasError ? 'Invalid email format' : null,
);

// Password Field with eye toggle
PasswordField(
  label: 'Password',
  hintText: 'Enter your password',
);

// 4-Digit OTP / PIN Field
CodeField(
  length: 4,
  onChanged: (pin) {
    if (pin.length == 4) verifyPin(pin);
  },
);

// Single Select Field (Bottom Sheet or Overlay menu)
SelectField<String>(
  label: 'Country / Region',
  unselectedString: 'Choose your region',
  options: const [
    SelectFieldOption(title: 'United States', value: 'US'),
    SelectFieldOption(title: 'Canada', value: 'CA'),
    SelectFieldOption(title: 'United Kingdom', value: 'UK'),
  ],
  makeOverlay: true, // false for modal bottom sheet
  enableSearch: true,
  onSelected: (code) => print('Selected: $code'),
);

// Multi-Select Field with compact chips
MultiSelectField<String>(
  label: 'Skills',
  options: mySkillOptions,
  initialValue: const ['flutter', 'dart'],
  initialValueComparison: (initial, val) => initial.contains(val),
  onSelected: (selectedList) => print(selectedList),
);

Animations & Shimmers

// Audio equalizer frequency wave visualizer
MusicVisualizer(
  barCount: 25,
  colors: [Colors.blue, Colors.purple],
  duration: [900, 700, 600, 800, 500],
);

// Shimmer skeleton loading placeholder
AnimatedPlaceholder(
  height: 60,
  width: double.infinity,
  borderRadius: BorderRadius.circular(12),
);

// Accordion Expand/Collapse Switcher
AnimatedFadeHeightSwitcher(
  expanded: _isSectionOpen,
  child: MyDetailsWidget(),
);

Lists & Slivers

// Auto-animating collection diff list
AnimatableStateListView<TaskItem>(
  items: tasks,
  idMapper: (task) => task.id,
  itemBuilder: (context, index, animation, task) {
    return SizeTransition(
      sizeFactor: animation,
      child: ListTile(title: Text(task.title)),
    );
  },
);

// Sticking or viewport-filling footer in CustomScrollViews
CustomScrollView(
  slivers: [
    SliverList(...),
    SliverFooter(
      fillRemaining: true,
      footer: LegalDisclaimerWidget(),
    ),
  ],
);

Utilities & Modals

// Theme-styled modal dialogues
showAppModal(
  context,
  title: const Text('Confirm Action'),
  message: const Text('Are you sure you want to proceed?'),
  actions: [
    OutlinedButton.small(text: 'Cancel', onPressed: () => Navigator.pop(context)),
    ContainedButton.small(text: 'Confirm', onPressed: _onConfirm),
  ],
);

// Toast alert snackbars
showSnackBarAlert(
  context,
  title: 'Profile Updated',
  message: 'Your settings have been saved.',
  type: SnackbarAlertType.success,
);

// Countdown timer for OTP expirations and promotions
TimerCountDownBuilder(
  toDate: DateTime.now().add(const Duration(minutes: 10)),
  builder: (context, state) {
    return Text('Expires in: ${state.timeToEndFormatted}');
  },
);

Screen Templates

flutter_gb_ui_kit comes bundled with high-converting, accessible screen templates to jumpstart app development:

Template Description
LoginTemplate Authentication view with email, password, remember me, and forgot password triggers.
SignUpTemplate Registration view with terms acceptance, dynamic validations, and login redirect.
RequestPasswordResetTemplate Password recovery request with instructions and email field.
ResetPasswordCodeInputTemplate Verification code (OTP) input with resend countdown timer.
ResetPasswordSetTemplate Form view to input and confirm new password credentials.
AccountCodeConfirmationTemplate Account activation code entry with resend timer.
LoadingTemplate Branded full-screen loader with animated indicators and status copy.
ErrorTemplate Friendly error presentation with retry action handling.

Detailed template documentation and visual previews can be found in docs/TEMPLATE_SCREENS.md.

Running the Example App

The example/ folder contains a full catalog application demonstrating every component in action with live Material 3 theme switching (6 curated palettes and 4 corner-radius presets).

To run the interactive showcase:

cd example
flutter pub get
flutter run

Migration Guide

If you are upgrading from flutter_gb_ui_kit v3.x or earlier (projects using legacy GBTheme, GBThemeData, or GBText), see our comprehensive MIGRATION_GUIDE.md for step-by-step instructions.

Libraries

constants/colors
constants/constants
flutter_gb_ui_kit
generated/intl/messages_all
generated/intl/messages_ar
generated/intl/messages_en
generated/intl/messages_es
generated/intl/messages_fr
generated/intl/messages_sv
generated/l10n
presentation/animations/animated_displayable
presentation/animations/animated_fade_height_switcher
presentation/animations/animated_placeholder
presentation/animations/animations
presentation/animations/audio_visualizer
presentation/app_bar/app_bar
presentation/app_bar/sliver_app_bar
presentation/buttons/button_child
presentation/buttons/button_progress_indicator
presentation/buttons/buttons
presentation/buttons/contained_button
presentation/buttons/gb_button_gradient
presentation/buttons/outlined_button
presentation/icons/g_b_icons_icons
Flutter icons GBIcons Copyright (C) 2020 by original authors @ fluttericon.com, fontello.com This font was generated by FlutterIcon.com, which is derived from Fontello.
presentation/icons/icons
presentation/inputs/address_state_select_field/address_state_select_field
presentation/inputs/code_field/code_field
presentation/inputs/inputs
presentation/inputs/password_field/password_field
presentation/inputs/select_field/select_field
presentation/inputs/select_field/select_field_option
presentation/inputs/switcher/switcher
presentation/inputs/text_field/input_wrapper
presentation/inputs/text_field/text_field
presentation/lists_views/animatable_state_list_view
presentation/lists_views/list_views
presentation/modals_and_messages/modals
presentation/modals_and_messages/modals_and_messages
presentation/modals_and_messages/snackbar
presentation/navbar/bottom_nav_bar
presentation/navbar/default_bottom_item
presentation/presentation
presentation/slivers/slivers
presentation/template_screens/account_code_confirmation_template
presentation/template_screens/error_template
presentation/template_screens/loading_template
presentation/template_screens/login_template
presentation/template_screens/reset_password_code_input_template
presentation/template_screens/reset_password_request_template
presentation/template_screens/reset_password_set_template
presentation/template_screens/signup_template
presentation/template_screens/template_screens
presentation/text/composed_action_text
presentation/text/input_feedback_container
presentation/text/input_feedback_text
presentation/text/text
presentation/theme/gb_contained_button_theme
presentation/theme/gb_input_decoration_theme
presentation/theme/gb_theme
presentation/theme/gb_theme_data
presentation/theme/gb_theme_factory
presentation/theme/theme
presentation/utils/child_size_listener
presentation/utils/color_utils
presentation/utils/gb_scaffold
presentation/utils/generic_data_handler_widget
presentation/utils/generic_error_retry
presentation/utils/handle_paste_builder
presentation/utils/have_an_account_legend
presentation/utils/loading_debounced_builder
presentation/utils/loading_debounced_switcher
presentation/utils/overlay_canvas
presentation/utils/screen_loading_indicator
presentation/utils/selectable_radio
presentation/utils/set_new_password_fields
presentation/utils/stepper
presentation/utils/time_picker
presentation/utils/timer_count_down_builder
presentation/utils/utils
presentation/utils/viewport_overflow_listener
types/button_enum
types/properties
types/types
types/widget_position