theme_extensions_builder #

theme_extensions_builder is a powerful code generator for Flutter's ThemeExtension classes. It eliminates boilerplate code by automatically generating copyWith, lerp, ==, and hashCode methods, along with convenient BuildContext extensions for easy theme access.

🎯 Features #

✅ Automatic code generation for ThemeExtension classes
✅ BuildContext extensions for convenient theme access
✅ Type-safe theme management with full IDE support
✅ Supports complex types: Colors, TextStyles, EdgeInsets, Durations, enums, and custom types
✅ Customizable constructor names for advanced use cases
✅ Smart lerp implementation with proper null handling
✅ Two annotation types: @ThemeExtensions and @ThemeGen

📦 Installation #

Add these packages to your project:

flutter pub add --dev build_runner
flutter pub add --dev theme_extensions_builder
flutter pub add theme_extensions_builder_annotation

Or add manually to pubspec.yaml:

dependencies:
  theme_extensions_builder_annotation: ^7.0.0

dev_dependencies:
  build_runner: ^2.4.0
  theme_extensions_builder: ^7.0.0

🚀 Quick Start #

1. Import and Setup #

Create a Dart file with the necessary imports and part directive:

// lib/theme/app_theme.dart

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

part 'app_theme.g.theme.dart';

Important: The part file must follow the pattern <filename>.g.theme.dart

2. Define Your Theme Extension #

@ThemeExtensions()
class AppTheme extends ThemeExtension<AppTheme> with _$AppThemeMixin {
  const AppTheme({
    required this.primaryColor,
    required this.secondaryColor,
    required this.spacing,
    this.borderRadius,
  });

  final Color primaryColor;
  final Color secondaryColor;
  final double spacing;
  final BorderRadius? borderRadius;
}

3. Generate Code #

Run the build runner:

# One-time generation
dart run build_runner build

# Watch mode (rebuilds on file changes)
dart run build_runner watch

4. Use Your Theme #

Add the extension to your ThemeData:

final lightTheme = ThemeData.light().copyWith(
  extensions: [
    AppTheme(
      primaryColor: Colors.blue,
      secondaryColor: Colors.green,
      spacing: 16.0,
      borderRadius: BorderRadius.circular(8.0),
    ),
  ],
);

final darkTheme = ThemeData.dark().copyWith(
  extensions: [
    AppTheme(
      primaryColor: Colors.indigo,
      secondaryColor: Colors.teal,
      spacing: 16.0,
      borderRadius: BorderRadius.circular(8.0),
    ),
  ],
);

Access the theme in your widgets:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Generated BuildContext extension for easy access
    final appTheme = context.appTheme;
    
    return Container(
      padding: EdgeInsets.all(appTheme.spacing),
      decoration: BoxDecoration(
        color: appTheme.primaryColor,
        borderRadius: appTheme.borderRadius,
      ),
      child: Text('Hello World'),
    );
  }
}

📚 Documentation #

@ThemeExtensions Annotation #

The primary annotation for generating ThemeExtension classes with full functionality.

Basic Usage

@ThemeExtensions()
class ButtonTheme extends ThemeExtension<ButtonTheme> with _$ButtonThemeMixin {
  const ButtonTheme({
    required this.backgroundColor,
    required this.foregroundColor,
    this.borderRadius,
    this.padding,
  });

  final Color backgroundColor;
  final Color foregroundColor;
  final BorderRadius? borderRadius;
  final EdgeInsets? padding;
}

Custom Context Accessor Name

@ThemeExtensions(contextAccessorName: 'customButtonTheme')
class ButtonTheme extends ThemeExtension<ButtonTheme> with _$ButtonThemeMixin {
  // ...
}

// Usage:
final theme = context.customButtonTheme; // Instead of context.buttonTheme

Disable BuildContext Extension

@ThemeExtensions(buildContextExtension: false)
class ButtonTheme extends ThemeExtension<ButtonTheme> with _$ButtonThemeMixin {
  // ...
}

// Manual access required:
final theme = Theme.of(context).extension<ButtonTheme>()!;

Custom Constructor

@ThemeExtensions(constructor: '_internal')
class ButtonTheme extends ThemeExtension<ButtonTheme> with _$ButtonThemeMixin {
  const ButtonTheme._internal({
    required this.backgroundColor,
    required this.foregroundColor,
  });

  final Color backgroundColor;
  final Color foregroundColor;

  // Factory constructor for user convenience
  factory ButtonTheme({
    required Color backgroundColor,
    required Color foregroundColor,
  }) = ButtonTheme._internal;
}

@ThemeGen Annotation #

Alternative annotation for theme data classes that don't extend ThemeExtension.

@ThemeGen()
class AlertThemeData with _$AlertThemeData {
  const AlertThemeData({
    this.canMerge = true,
    this.transitionDuration = const Duration(milliseconds: 300),
    this.iconPadding,
    this.titleTextStyle,
    this.borderRadius,
  });

  @override
  final bool canMerge;
  final Duration transitionDuration;
  final EdgeInsetsGeometry? iconPadding;
  final TextStyle? titleTextStyle;
  final double? borderRadius;

  static AlertThemeData? lerp(AlertThemeData? a, AlertThemeData? b, double t) =>
      _$AlertThemeData.lerp(a, b, t);
}

Generated Code #

The generator creates:

Mixin with methods:
- copyWith() - Create a copy with modified fields
- lerp() - Interpolate between two theme instances
- merge() - Merge two theme instances
- operator == - Equality comparison
- hashCode - Hash code for collections
BuildContext extension (if enabled):
- Convenient getter for accessing the theme

Example of generated code:

part of 'alert_theme_data.dart';

// **************************************************************************
// ThemeGenGenerator
// **************************************************************************

mixin _$AlertThemeData {
  bool get canMerge => true;

  static AlertThemeData? lerp(AlertThemeData? a, AlertThemeData? b, double t) {
    if (a == null && b == null) {
      return null;
    }

    return AlertThemeData(
      canMerge: b?.canMerge ?? true,
      transitionDuration: lerpDuration$(
        a?.transitionDuration,
        b?.transitionDuration,
        t,
      )!,
      iconPadding: EdgeInsetsGeometry.lerp(a?.iconPadding, b?.iconPadding, t),
      titleTextStyle: TextStyle.lerp(a?.titleTextStyle, b?.titleTextStyle, t),
      borderRadius: lerpDouble$(a?.borderRadius, b?.borderRadius, t),
    );
  }

  AlertThemeData copyWith({
    bool? canMerge,
    Duration? transitionDuration,
    EdgeInsetsGeometry? iconPadding,
    TextStyle? titleTextStyle,
    double? borderRadius,
  }) {
    final a = (this as AlertThemeData);

    return AlertThemeData(
      canMerge: canMerge ?? a.canMerge,
      transitionDuration: transitionDuration ?? a.transitionDuration,
      iconPadding: iconPadding ?? a.iconPadding,
      titleTextStyle: titleTextStyle ?? a.titleTextStyle,
      borderRadius: borderRadius ?? a.borderRadius,
    );
  }

  AlertThemeData merge(AlertThemeData? other) {
    final current = (this as AlertThemeData);

    if (other == null) {
      return current;
    }

    if (!other.canMerge) {
      return other;
    }

    return copyWith(
      canMerge: other.canMerge,
      transitionDuration: other.transitionDuration,
      iconPadding: other.iconPadding,
      titleTextStyle:
          current.titleTextStyle?.merge(other.titleTextStyle) ??
          other.titleTextStyle,
      borderRadius: other.borderRadius,
    );
  }

  @override
  bool operator ==(Object other) {
    if (identical(this, other)) {
      return true;
    }

    if (other is! AlertThemeData) {
      return false;
    }

    final value = (this as AlertThemeData);

    return other.canMerge == value.canMerge &&
        other.transitionDuration == value.transitionDuration &&
        other.iconPadding == value.iconPadding &&
        other.titleTextStyle == value.titleTextStyle &&
        other.borderRadius == value.borderRadius;
  }

  @override
  int get hashCode {
    final value = (this as AlertThemeData);

    return Object.hash(
      runtimeType,
      value.canMerge,
      value.transitionDuration,
      value.iconPadding,
      value.titleTextStyle,
      value.borderRadius,
    );
  }
}

🎨 Advanced Examples #

Multiple Theme Extensions #

You can define multiple theme extensions in the same file:

@ThemeExtensions()
class AppColors extends ThemeExtension<AppColors> with _$AppColorsMixin {
  const AppColors({
    required this.primary,
    required this.secondary,
    required this.error,
  });

  final Color primary;
  final Color secondary;
  final Color error;
}

@ThemeExtensions()
class AppTypography extends ThemeExtension<AppTypography> with _$AppTypographyMixin {
  const AppTypography({
    required this.heading,
    required this.body,
    required this.caption,
  });

  final TextStyle heading;
  final TextStyle body;
  final TextStyle caption;
}

// Usage in ThemeData
final theme = ThemeData.light().copyWith(
  extensions: [
    AppColors(
      primary: Colors.blue,
      secondary: Colors.green,
      error: Colors.red,
    ),
    AppTypography(
      heading: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
      body: TextStyle(fontSize: 16),
      caption: TextStyle(fontSize: 12, color: Colors.grey),
    ),
  ],
);

🛠️ IDE Configuration #

VS Code - File Nesting #

Add to your .vscode/settings.json to automatically nest generated files:

{
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.patterns": {
    "*.dart": "${capture}.g.theme.dart"
  }
}

Android Studio / IntelliJ IDEA #

Go to Settings → Editor → File Nesting
Add pattern: *.dart → ${name}.g.theme.dart

📦 Packages #

This project consists of two packages:

theme_extensions_builder - The code generator
theme_extensions_builder_annotation - Annotations

📖 Example #

Check out the example project for a comprehensive Flutter app demonstrating: