Max UI V1

A production-ready Flutter UI component library with theme-aware widgets and extensive customization options.

Features

MaxUIAppBar — Custom app bar with gradients, shadows, and flexible layout
MaxUISnackbar — Success, error, warning, and info snackbars
MaxUIDropdown — Generic dropdown with custom item builders
MaxUIDropdownField — Labeled pill-style dropdown with loading state
MaxUITextField — Labeled text field with pill-shaped borders
MaxUIBottomNavBar — Animated bottom navigation with SVG or icon support
MaxUIContainer — Container, card, and gradient variants
MaxUIBottomSheet — Modal bottom sheet with drag handle
MaxUIImagePickerSheet — Camera / gallery picker UI (UI only)
MaxUIColors — Global color palette for all form and nav components

Installation

Add to pubspec.yaml:

dependencies:
  max_ui_v1: ^1.0.0

flutter pub get

flutter_svg is included automatically. You only need to declare SVG assets in your app when using MaxUIBottomNavDestination.iconPath.

Run the example

cd example
flutter pub get
flutter run

Quick start

import 'package:max_ui_v1/max_ui_v1.dart';

void main() {
  MaxUIColors.configure(primary: const Color(0xFF009688));
  runApp(const MyApp());
}

Components

1. MaxUIAppBar

Scaffold(
  appBar: MaxUIAppBar(
    title: 'My App',
    actions: [IconButton(icon: Icon(Icons.search), onPressed: () {})],
    backgroundColor: Colors.teal,
    titleColor: Colors.white,
    showShadow: true,
    centerTitle: false,
  ),
  body: const SizedBox(),
);

Use titleWidget for a custom title, or decoration to override the entire bar background.

2. MaxUISnackbar

MaxUISnackbar.success(context: context, message: 'Saved!');
MaxUISnackbar.error(context: context, message: 'Failed!');
MaxUISnackbar.warning(context: context, message: 'Be careful!');
MaxUISnackbar.info(context: context, message: 'Note');

// Full control
MaxUISnackbar.show(
  context: context,
  message: 'Custom',
  type: SnackbarType.info,
  backgroundColor: Colors.black87,
  duration: const Duration(seconds: 5),
  action: SnackBarAction(label: 'Undo', onPressed: () {}),
);

3. MaxUITextField

MaxUITextField(
  label: 'Email',
  hint: 'Enter your email',
  keyboardType: TextInputType.emailAddress,
  prefixIcon: const Icon(Icons.email_outlined),
  validator: (v) => v?.isEmpty == true ? 'Required' : null,
  onChanged: (v) => print(v),
);

// Full override
MaxUITextField(
  label: 'Notes',
  hint: 'Type here',
  decoration: InputDecoration(
    hintText: 'Type here',
    border: OutlineInputBorder(borderRadius: BorderRadius.circular(8)),
  ),
);

4. MaxUIDropdown

Generic dropdown for any type T.

MaxUIDropdown<String>(
  items: const ['A', 'B', 'C'],
  value: selected,
  hint: 'Pick one',
  onChanged: (v) => setState(() => selected = v),
);

// Custom rows
MaxUIDropdown<User>(
  items: users,
  value: selectedUser,
  hint: 'Select user',
  itemBuilder: (context, user) => MaxUIDropdownItem(
    label: user.name,
    leadingIcon: Icons.person,
  ),
  onChanged: (user) => setState(() => selectedUser = user),
);

5. MaxUIDropdownField

Labeled dropdown with pill styling and a built-in loading state.

MaxUIDropdownField(
  label: 'Country',
  hint: 'Select country',
  value: country,
  items: countries,
  isLoading: countries.isEmpty,
  onChanged: (v) => setState(() => country = v),
);

// Custom menu rows
MaxUIDropdownField(
  label: 'City',
  hint: 'Select city',
  value: city,
  items: cities,
  itemBuilder: (context, item) => ListTile(title: Text(item)),
  onChanged: (v) => setState(() => city = v),
);

6. MaxUIBottomNavBar

int _index = 0;

Scaffold(
  body: Center(child: Text('Tab $_index')),
  bottomNavigationBar: MaxUIBottomNavBar(
    currentIndex: _index,
    onTap: (i) => setState(() => _index = i),
    destinations: const [
      MaxUIBottomNavDestination(icon: Icons.home_outlined, label: 'Home'),
      MaxUIBottomNavDestination(icon: Icons.person_outline, label: 'Profile'),
    ],
  ),
);

// With SVG assets (declare in your app's pubspec.yaml)
MaxUIBottomNavDestination(
  iconPath: 'assets/icons/home.svg',
  label: 'Home',
)

Use itemBuilder for fully custom tab widgets, or pass colors via selectedColor / unselectedColor.

7. MaxUIContainer

// Basic
MaxUIContainer(
  padding: const EdgeInsets.all(16),
  borderRadius: 12,
  backgroundColor: Colors.white,
  showShadow: true,
  child: const Text('Hello'),
);

// Card (tappable with ripple)
MaxUICard(
  onTap: () => print('tapped'),
  child: const Text('Card content'),
);

// Gradient
MaxUIGradientContainer(
  gradient: const LinearGradient(colors: [Colors.blue, Colors.purple]),
  child: const Text('Gradient', style: TextStyle(color: Colors.white)),
);

Pass decoration on MaxUIContainer to override the entire box decoration.

8. MaxUIBottomSheet

MaxUIBottomSheet.show(
  context: context,
  title: 'Options',
  child: Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      ListTile(title: const Text('Edit'), onTap: () => Navigator.pop(context)),
      ListTile(title: const Text('Delete'), onTap: () => Navigator.pop(context)),
    ],
  ),
);

// Fully custom content
MaxUIBottomSheetBuilder.showCustom(
  context: context,
  builder: (context) => MyCustomSheet(),
);

9. MaxUIImagePickerSheet

UI only — wire up your own image_picker or native logic in the callback.

MaxUIImagePickerSheet.show(
  context: context,
  onSourceSelected: (source) {
    if (source == ImagePickerSource.camera) {
      pickFromCamera();
    } else {
      pickFromGallery();
    }
  },
);

// Hide options / customize labels and icons
MaxUIImagePickerSheet.showAdvanced(
  context: context,
  title: 'Add Photo',
  showCamera: true,
  showGallery: true,
  cameraIcon: Icons.camera_alt,
  onSourceSelected: (source) => handleSource(source),
);

Theming

MaxUIColors

Set brand colors once for all form and navigation widgets:

MaxUIColors.configure(
  primary: const Color(0xFF009688),
  border: const Color(0xFFE0E0E0),
  textDark: const Color(0xFF212121),
  fieldFill: const Color(0xFFF8F8F8),
);

MaxUIColors.reset(); // restore defaults

Individual widgets also accept their own color, padding, and style parameters. Pass decoration, InputDecoration, or builder callbacks when you need full control.

Customization cheat sheet

Quick reference for the most useful knobs per widget. All are optional unless marked required.

Global

Knob	Type	Purpose
`MaxUIColors.configure(...)`	static	Set `primary`, `border`, `textDark`, `fieldFill` app-wide
`MaxUIColors.reset()`	static	Restore default palette

MaxUIAppBar

Knob	Purpose
`title` required	Title text
`titleWidget`	Replace default title widget
`leading` / `actions`	Left and right widgets
`backgroundColor` / `backgroundGradient`	Bar background
`titleColor` / `titleStyle`	Title appearance
`height` / `padding`	Size and insets
`showShadow` / `elevation` / `shadowColor` / `shadowOffset`	Shadow control
`centerTitle` / `onTitleTap`	Layout and interaction
`decoration`	Full background override
`bottom` / `bottomBorder` / `safeAreaTop`	Extra chrome

MaxUISnackbar

Knob	Purpose
`.success` / `.error` / `.warning` / `.info`	Preset types
`message` required	Snackbar text
`backgroundColor` / `iconColor` / `textColor`	Override preset colors
`icon` / `leading` / `content`	Custom icon or entire content row
`duration` / `action`	Timing and action button
`margin` / `padding` / `width` / `elevation`	Layout
`borderRadius` / `shape` / `behavior`	Shape and floating style
`dismissDirection` / `showCloseIcon`	Dismiss behaviour

MaxUITextField

Knob	Purpose
`label` / `hint` required	Label and placeholder
`controller` / `focusNode` / `validator`	Form wiring
`keyboardType` / `obscureText` / `maxLines` / `readOnly`	Input behaviour
`prefixIcon` / `suffixIcon` / `prefix` / `suffix`	Field adornments
`onChanged` / `onFieldSubmitted` / `onTap` / `onTapOutside`	Callbacks
`labelStyle` / `textStyle` / `hintStyle` / `errorStyle`	Typography
`fillColor` / `borderColor` / `focusedBorderColor` / `errorBorderColor`	Colors
`borderRadius` / `borderWidth` / `contentPadding`	Shape and spacing
`labelSpacing` / `bottomSpacing` / `showLabel` / `labelWidget`	Layout
`decoration`	Full `InputDecoration` override

MaxUIDropdown<T>

Knob	Purpose
`items` / `onChanged` required	Data and selection callback
`value` / `hint`	Current selection and placeholder
`itemBuilder` / `selectedItemBuilder` / `hintBuilder`	Custom widgets per row
`enabled` / `isExpanded` / `isDense` / `alignment`	Behaviour and layout
`borderRadius` / `borderWidth` / `showBorder`	Shape
`backgroundColor` / `borderColor` / `dropdownColor`	Colors
`hintStyle` / `valueStyle`	Text styles
`dropdownIcon` / `icon` / `iconColor` / `iconSize`	Chevron
`contentPadding` / `menuMaxHeight` / `itemHeight` / `elevation`	Menu sizing
`decoration`	Full outer `BoxDecoration` override

MaxUIDropdownField

Knob	Purpose
`label` / `hint` / `items` / `onChanged` required	Core field setup
`value`	Current selection
`isLoading` / `readOnly`	Loading spinner vs disabled
`labelWidget` / `labelStyle` / `showLabel`	Label area
`hintStyle` / `valueStyle` / `itemStyle`	Text styles
`fillColor` / `borderColor` / `dropdownColor` / `iconColor`	Colors
`borderRadius` / `fieldPadding` / `itemPadding`	Shape and insets
`boxShadow` / `elevation` / `menuMaxHeight`	Menu depth and size
`dropdownIcon` / `iconSize`	Chevron
`loadingWidget` / `loadingHeight`	Custom loading state
`itemBuilder` / `selectedBuilder`	Custom menu rows
`decoration` / `dropdownDecoration`	Outer and inner box overrides

MaxUIBottomNavBar

Knob	Purpose
`currentIndex` / `onTap` / `destinations` required	Tab state
`MaxUIBottomNavDestination.label` required	Tab label
`icon` / `iconPath` / `iconWidget`	Icon source (Material, SVG, or custom widget)
`selectedColor` / `unselectedColor` / `backgroundColor`	Colors
`backgroundGradient` / `boxShadow` / `borderRadius` / `border`	Bar chrome
`padding` / `itemPadding` / `mainAxisAlignment`	Layout
`selectedScale` / `scaleDuration` / `scaleCurve`	Icon animation
`labelStyle` / `selectedLabelStyle` / `useMarquee`	Label appearance
`showSafeAreaPadding` / `extraBottomPadding`	Bottom inset
`itemBuilder`	Full custom tab widget
`decoration`	Full bar background override

MaxUIContainer / MaxUICard / MaxUIGradientContainer

Knob	Purpose
`child` required	Inner content
`backgroundColor` / `backgroundGradient`	Fill
`padding` / `margin` / `width` / `height`	Size and spacing
`borderRadius` / `borderColor` / `borderWidth` / `border`	Borders
`showShadow` / `elevation` / `shadowColor` / `shadowOffset`	Shadow
`alignment` / `constraints` / `clipBehavior`	Layout
`onTap` / `enableTap`	Tap handling
`decoration`	Full `BoxDecoration` override (Container only)
`onTap` / `showRipple`	Tap + ripple (Card only)
`gradient`	Background gradient (GradientContainer only)

MaxUIBottomSheet

Knob	Purpose
`context` / `child` required	Sheet host and body
`title` / `titleWidget` / `header`	Header area
`showDragIndicator` / `dragIndicatorWidth` / `dragIndicatorColor`	Drag handle
`maxHeight` / `constraints` / `contentPadding`	Size
`backgroundColor` / `borderRadius` / `shape`	Appearance
`showCloseButton` / `closeIcon` / `titleStyle`	Header controls
`showDivider` / `dividerColor`	Separator below title
`enableDrag` / `isDismissible` / `animationDuration`	Behaviour
`wrapper`	Wrap entire sheet content
`MaxUIBottomSheetBuilder.showCustom` + `builder`	Fully custom sheet

MaxUIImagePickerSheet

Knob	Purpose
`context` / `onSourceSelected` required	Show sheet and handle pick
`title` / `titleWidget`	Header
`cameraLabel` / `galleryLabel` + descriptions	Option text
`showCamera` / `showGallery`	Toggle sources (advanced)
`cameraIcon` / `galleryIcon` / `cameraLeading` / `galleryLeading`	Icons
`optionStyle` (`MaxUIImagePickerOptionStyle`)	Row padding, borders, icon box, text
`optionBuilder`	Full custom option row
`maxHeight` / `backgroundColor` / `borderRadius`	Sheet chrome (passed to bottom sheet)

CharacterBasedMarquee

Used internally by bottom nav labels; can be used standalone.

Knob	Purpose
`child` required	Usually a `Text` widget
`widthInCharacters` required	Scroll threshold
`duration` / `minDuration` / `maxDuration`	Scroll speed
`gap` / `widthFactor` / `curve`	Animation tuning

Project structure

lib/
├── max_ui_v1.dart
└── src/
    ├── components/
    │   ├── appbar/
    │   ├── snackbar/
    │   ├── text_field/
    │   ├── dropdown/
    │   ├── dropdown_field/
    │   ├── bottom_nav/
    │   ├── container/
    │   ├── bottom_sheet/
    │   └── image_picker_sheet/
    ├── theme/
    │   └── max_ui_colors.dart
    └── widgets/
        └── character_based_marquee.dart
test/components/          # Widget tests per component
example/                  # Demo app (pub.dev standard)

Testing

flutter test

Example app

cd example && flutter run

The demo in example/lib/main.dart exercises every component interactively.

Publishing

This package is configured for pub.dev. Before publishing:

dart pub publish --dry-run   # verify no errors
dart pub publish             # publish (requires pub.dev login)

Ensure you have publisher rights for the package name max_ui_v1 on pub.dev.

Changelog

v1.0.0

Initial release with AppBar, Snackbar, Dropdown, Container, Bottom Sheet, Image Picker
Added MaxUITextField, MaxUIDropdownField, MaxUIBottomNavBar
Added MaxUIColors and CharacterBasedMarquee
Extensive customization parameters on all components

License

MIT License — see LICENSE for details.