modula_ui 1.0.3

A comprehensive Flutter UI component library with 100+ professionally designed widgets and full Material 3 theming support.

Modula UI

A comprehensive Flutter UI component library with 100+ professionally designed widgets and full Material 3 theming support. Build beautiful, consistent, and accessible Flutter applications with ease.

✨ Features

• 🎨 100+ Components - Complete collection of UI widgets across 7 categories
• 🌓 Material 3 Design - Full compliance with latest Material Design guidelines
• 🌙 Dark Mode - Beautiful light and dark themes with smooth transitions
• 🎭 Highly Customizable - Extensive customization options for every component
• 🔒 Type-Safe - Strong typing with comprehensive enum support
• ✅ Production Ready - Battle-tested components with example implementations
• 🚀 Easy to Use - Simple API with sensible defaults
• 📱 Cross-Platform - Works seamlessly on iOS, Android, Web, and Desktop

📦 Component Categories

🔘 Buttons (13 components)

Primary, Secondary, Tertiary, Icon, Text, Outlined, FAB, Toggle, Dropdown, Share, Hamburger, Expandable, Loading Button

🖼️ Display (16 components)

Card, Avatar, Badge, Chip, Tooltip, Banner, Divider, Progress Indicators, Skeleton, Accordion, Rating, Carousel, Timeline, DataTable, ListTile, Error State

📝 Inputs (17 components)

TextField, SearchField, TextArea, Dropdown, Checkbox, Radio, Switch, Slider, RangeSlider, Stepper, DateTimePicker, ColorPicker, PinCode, ChipsInput, TagInput, SliderButton, Calendar

📐 Layout (7 components)

Responsive, Grid, CardContainer, AppBar, Scaffold, ExpansionPanel, FlexHelpers

🧭 Navigation (5 components)

TabBar, BottomNavigationBar, Drawer, Breadcrumbs, Pagination

💬 Feedback (9 components)

Snackbar, Dialog, BottomSheet, Popover, ValidationMessage, Toast, PullToRefresh, InfiniteScroll, Menu

✨ Animations (24 components)

FadeIn/Out, SlideIn/Out, ScaleIn/Out, FlipIn, RotateIn/Out, BounceIn, ElasticIn, ExpandIn, ShrinkAway, AttentionSeeker, Staggered animations, and more

🚀 Getting Started

Installation

Add modula_ui to your pubspec.yaml:

dependencies:
  modula_ui: ^1.0.0

Then install it:

flutter pub get

Basic Usage

import 'package:modula_ui/exporter/exporter.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return ModulaApp(
      title: 'My Awesome App',
      themeMode: ThemeMode.system, // Supports light, dark, and system
      home: const HomePage(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: ModulaAppBar(
        title: const Text('Welcome to Modula UI'),
        elevation: 2,
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ModulaPrimaryButton(
              text: 'Click Me',
              onPressed: () {
                ModulaSnackbar.showSuccess(
                  context: context,
                  message: 'Button pressed!',
                );
              },
            ),
          ],
        ),
      ),
    );
  }
}

🎨 Theming

Modula UI provides comprehensive theming with full Material 3 support.

Default Theme

ModulaApp(
  themeMode: ThemeMode.system, // Auto-switches based on system
  home: YourHomeScreen(),
)

Custom Theme

ModulaApp(
  theme: ModulaThemeData(
    brightness: Brightness.light,
    colors: ModulaColorScheme.fromBrightness(Brightness.light),
  ),
  darkTheme: ModulaThemeData(
    brightness: Brightness.dark,
    colors: ModulaColorScheme.fromBrightness(Brightness.dark),
  ),
  themeMode: ThemeMode.system,
  home: YourHomeScreen(),
)

Accessing Theme

// Access current theme
final theme = ModulaTheme.of(context);

// Use theme colors
Container(
  color: theme.colors.light.primary,
  child: Text(
    'Hello',
    style: theme.typography?.defaultTextStyele.h4,
  ),
)

📖 Component Examples

Buttons

// Primary Button
ModulaPrimaryButton(
  text: 'Submit',
  onPressed: () {},
  icon: Icons.check,
  isLoading: false,
)

// FAB Button
ModulaFabButton(
  icon: Icons.add,
  onPressed: () {},
  size: FabSize.regular,
)

// Toggle Button
ModulaToggleButton(
  options: ['Option 1', 'Option 2', 'Option 3'],
  selectedIndex: 0,
  onToggle: (index) {},
)

Display Components

// Avatar
ModulaAvatar(
  imageUrl: 'https://example.com/avatar.jpg',
  size: AvatarSize.large,
  shape: AvatarShape.circle,
)

// Badge
ModulaBadge(
  count: 5,
  position: BadgePosition.topRight,
  child: Icon(Icons.notifications),
)

// Chip
ModulaChip(
  label: 'Flutter',
  onDeleted: () {},
  avatar: CircleAvatar(child: Text('F')),
)

// Card Container
ModulaCardContainer(
  elevation: 4,
  padding: EdgeInsets.all(16),
  child: Column(
    children: [
      Text('Card Title'),
      Text('Card content goes here'),
    ],
  ),
)

// Progress Indicator
ModulaCircularProgressIndicator(
  value: 0.7, // 70%
  showPercentage: true,
  size: 100,
)

Input Components

// Text Field
ModulaTextField(
  label: 'Email',
  hint: 'Enter your email',
  validator: (value) => value?.isEmpty ?? true ? 'Required' : null,
  prefixIcon: Icons.email,
)

// Dropdown
ModulaDropdown<String>(
  value: selectedValue,
  items: ['Option 1', 'Option 2', 'Option 3']
      .map((e) => DropdownMenuItem(value: e, child: Text(e)))
      .toList(),
  onChanged: (value) => setState(() => selectedValue = value),
  hint: 'Select an option',
)

// Checkbox
ModulaCheckbox(
  value: isChecked,
  onChanged: (value) => setState(() => isChecked = value ?? false),
  label: 'Accept terms and conditions',
)

// Date Picker
ModulaDateTimePicker(
  initialDate: DateTime.now(),
  onDateSelected: (date) {},
  mode: DateTimeMode.date,
)

// Calendar
ModulaCalendar(
  selectedDates: selectedDates,
  onDateSelected: (date) {
    setState(() => selectedDates.add(date));
  },
  viewMode: ModulaCalendarViewMode.month,
)

DataTable

ModulaDataTable(
  columns: [
    ModulaDataColumn(label: 'Name', sortable: true),
    ModulaDataColumn(label: 'Age'),
    ModulaDataColumn(label: 'Email'),
  ],
  rows: [
    ModulaDataRow(
      cells: [
        ModulaDataCell(child: Text('John Doe')),
        ModulaDataCell(child: Text('25')),
        ModulaDataCell(child: Text('[e-mail]')),
      ],
      onSelectChanged: (selected) {},
    ),
  ],
  showCheckboxColumn: true,
  sortable: true,
)

Feedback Components

// Snackbar
ModulaSnackbar.showSuccess(
  context: context,
  message: 'Operation completed successfully!',
);

// Dialog
ModulaDialog.show(
  context: context,
  title: 'Confirm Action',
  content: 'Are you sure you want to proceed?',
  actions: [
    ModulaDialogAction(
      text: 'Cancel',
      onPressed: () => Navigator.pop(context),
    ),
    ModulaDialogAction(
      text: 'Confirm',
      onPressed: () {
        // Handle confirmation
        Navigator.pop(context);
      },
      isPrimary: true,
    ),
  ],
);

// Bottom Sheet
ModulaBottomSheet.show(
  context: context,
  builder: (context) => Container(
    padding: EdgeInsets.all(16),
    child: Column(
      children: [
        Text('Bottom Sheet Content'),
        ModulaPrimaryButton(
          text: 'Close',
          onPressed: () => Navigator.pop(context),
        ),
      ],
    ),
  ),
);

Animations

// Fade In Animation
ModulaFadeIn(
  duration: Duration(milliseconds: 500),
  child: YourWidget(),
)

// Slide In Animation
ModulaSlideIn(
  direction: SlideDirection.fromBottom,
  child: YourWidget(),
)

// Scale In Animation
ModulaScaleIn(
  delay: Duration(milliseconds: 200),
  child: YourWidget(),
)

// Staggered Animation
ModulaStaggeredFade(
  children: [
    Widget1(),
    Widget2(),
    Widget3(),
  ],
  staggerDelay: Duration(milliseconds: 100),
)

Layout Components

// Responsive Grid
ModulaGrid(
  crossAxisCount: 3,
  spacing: 16,
  children: [
    Card(child: Text('Item 1')),
    Card(child: Text('Item 2')),
    Card(child: Text('Item 3')),
  ],
)

// Expansion Panel
ModulaExpansionPanel(
  panels: [
    ExpansionPanelItem(
      headerBuilder: (context, isExpanded) => 
        Text('Panel Header'),
      body: Text('Panel content goes here'),
      isExpanded: false,
    ),
  ],
  style: ModulaExpansionPanelStyle.bordered,
)

🎯 Example App

Check out the comprehensive example app in the example/ folder to see all components in action:

cd example
flutter run

The example app includes:

• 📱 Interactive component showcase
• 🌓 Live theme switching (Light/Dark/System)
• ✅ All 100+ components with working examples
• 📝 Source code for each example
• 🔍 Search functionality to find components
• 📂 Organized by category

📚 Documentation

Core Concepts

1. ModulaApp - Main wrapper that provides theming and configuration
2. ModulaTheme - Access theme data anywhere in your widget tree
3. ModulaThemeData - Theme configuration (colors, typography, spacing)
4. ModulaPalette - Color schemes for light and dark modes

Best Practices

• Always wrap your app with ModulaApp instead of MaterialApp
• Use ModulaTheme.of(context) to access theme values
• Prefer Modula components over standard Flutter widgets for consistency
• Test your UI in both light and dark modes
• Use the example app as a reference for implementation

Migration from Standard Flutter

// Before
MaterialApp(
  home: Scaffold(
    appBar: AppBar(title: Text('Title')),
    body: ElevatedButton(
      onPressed: () {},
      child: Text('Button'),
    ),
  ),
)

// After
ModulaApp(
  home: Scaffold(
    appBar: ModulaAppBar(title: Text('Title')),
    body: ModulaPrimaryButton(
      text: 'Button',
      onPressed: () {},
    ),
  ),
)

🔧 Advanced Usage

Custom Colors

final customPalette = ModulaPalette(
  primary: Color(0xFF6750A4),
  onPrimary: Colors.white,
  secondary: Color(0xFF625B71),
  // ... define all required colors
);

ModulaApp(
  theme: ModulaThemeData(
    brightness: Brightness.light,
    colors: ModulaColorScheme(
      light: customPalette,
      dark: ModulaPalette.dark(),
    ),
  ),
)

Runtime Theme Switching

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  ThemeMode themeMode = ThemeMode.system;

  void toggleTheme() {
    setState(() {
      themeMode = themeMode == ThemeMode.light 
        ? ThemeMode.dark 
        : ThemeMode.light;
    });
  }

  @override
  Widget build(BuildContext context) {
    return ModulaApp(
      themeMode: themeMode,
      home: HomePage(onThemeToggle: toggleTheme),
    );
  }
}

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution Guidelines

• Follow the existing code style and conventions
• Test your changes in both light and dark modes
• Update documentation as needed
• Add examples for new components in the example app
• Ensure all tests pass
• Follow Material 3 design guidelines
• Maintain accessibility standards (WCAG 2.1)

🐛 Bug Reports & Feature Requests

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions

When reporting bugs, please include:

• Flutter version
• Modula UI version
• Platform (iOS/Android/Web/Desktop)
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if applicable

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ❤️ using Flutter
• Inspired by Material Design 3
• Icons from Material Icons
• Special thanks to all contributors

📊 Stats

• 100+ Production-ready components
• 7 Major categories
• Material 3 Fully compliant
• Dark Mode Native support
• Type-Safe 100% Dart null-safety

🗺️ Roadmap

Version 1.1.0

• ❌ Additional animation effects
• ❌ Enhanced accessibility features (screen reader support)
• ❌ Performance optimizations
• ❌ Additional form validators

Version 1.2.0

• ❌ Web-specific optimizations
• ❌ Desktop platform enhancements
• ❌ RTL (Right-to-Left) support
• ❌ Additional chart components

Version 2.0.0

• ❌ Headless components (logic-only widgets)
• ❌ Advanced gesture recognition
• ❌ Plugin architecture
• ❌ Figma design token integration

💡 Why Modula UI?

vs Standard Flutter Widgets

• ✅ Consistent design language across all components
• ✅ Built-in dark mode support
• ✅ Less boilerplate code
• ✅ Material 3 compliant out of the box

vs Other UI Libraries

• ✅ 100+ components vs 50-60 in most libraries
• ✅ Comprehensive theming system
• ✅ Extensive documentation and examples
• ✅ Active maintenance and updates
• ✅ Production-ready components

🔗 Links

• Pub.dev: pub.dev/packages/modula_ui
• GitHub: github.com/codecrafters42/modula_ui
• Documentation: GitHub Wiki

📞 Support & Community

• 💬 Discussions: Ask questions and share ideas
• 🐛 Issues: Report bugs and request features
• 📧 Email: [e-mail]
• 🐦 Twitter: @modula_ui

---

Made with ❤️ by the Modula UI Team
_{Empowering developers to build beautiful Flutter apps}