Rabbit #

Rabbit helps you create these wrapper widgets quickly and consistently, maintaining all the original widget's parameters while allowing you to customize what you need.

For example, given a Container widget:

Container(
  color: Colors.red,
  child: child,
)

Generate a RedContainer widget that encapsulates this styling and reuse it throughout your app:

RedContainer(
  child: child,
)

Table of Contents #

• Rabbit
  • Table of Contents
  • Requirements
  • Installation
  • Getting Started
  • Configuration Options
    • Example Configuration
    • widgets
    • output_dir
    • prefix
    • docs
    • pipeable
  • Multiple Constructors
  • Known Limitations
  • Maintaining Generated Code
  • Common Use Cases
    • Theming Widgets
    • Adding Default Behaviors
  • Best Practices
    • When to Use Wrappers
    • When Not to Use Wrappers
    • Naming Conventions
  • Complaints

Requirements #

• Flutter 3.22.0 or later

Installation #

Add Rabbit to your project's dependencies:

dart pub add rabbit

Or manually add it to your pubspec.yaml:

dependencies:
  rabbit: ^latest_version

Then run:

dart pub get

Getting Started #

In this example we will generate a RedContainer widget that is identical to a Container widget but with a red background color.

1. Configure your widget wrappers in pubspec.yaml:

   rabbit:
     widgets:
       package:flutter/material.dart:
         - Container
   

   For a complete list of configuration options, see the Configuration section.

2. Run the generation command:

     dart run rabbit generate
   

   This will generate a $Container widget in the default output directory.

   Important

   Rabbit does not handle imports perfectly. You may need to add or remove some imports manually.
   However, any other syntax errors are considered bugs, and you should open an issue if you encounter them.

3. Locate the generated widget and customize it as needed.

   class RedContainer extends StatelessWidget {
      
     final AlignmentGeometry alignment;
     final EdgeInsetsGeometry padding;
     // ... and the rest of the Container properties
   
     const RedContainer({
       super.key,
       this.alignment,
       this.padding,
       // ... and the rest of the Container properties
     });
   
   
     @override
     Widget build(BuildContext context) {
       return Container(
         color: Colors.red,
         alignment: alignment,
         padding: padding,
         // ... and the rest of the Container properties
       );
     }
   }
   

   You can now use the RedContainer widget in your app as you would a Container widget.

4. (Optional) Rename the generated file: Rename the generated file to red_container.dart for better readability and import statements.

Now you can use the RedContainer widget in your app as you would a Container widget.

RedContainer(
  child: Text('Hello, World!'),
)

Configuration Options #

The following options can be configured in your pubspec.yaml under the rabbit key:

Example Configuration #

rabbit:
  output_dir: lib/src/widgets
  prefix: My
  docs: true
  widgets:
    package:flutter/material.dart:
      - Container
      - ElevatedButton
    package:shadcn_ui/shadcn_ui.dart:
      - ShadButton

widgets #

The widgets option is a map where:

• Keys are package import statements
• Values are lists of widget names to generate wrappers for

You can use the special value all to generate wrappers for all widgets in a package:

rabbit:
  widgets:
    package:flutter/material.dart:
      - all  # Will generate wrappers for all Material widgets

⚠️ Warning: Using all will generate a large number of files and is not recommended for most use cases.

output_dir #

The directory where generated files will be placed.

rabbit:
  output_dir: lib/src/widgets  # Your custom path

• Default: lib/src/wrapped
• The directory will be created if it doesn't exist
• Relative paths are resolved from your project root
• The generate widgets will match the package structure of the original widgets

prefix #

The prefix added to generated widget names to avoid naming conflicts.

rabbit:
  prefix: My  # Will generate MyContainer, MyButton, etc.

• Default: $
• Can be set to an empty string ('') if you want no prefix

docs #

Controls whether documentation comments from the original widget are included.

rabbit:
  docs: true

• Default: false
• Includes parameter descriptions, examples, and other documentation
• Can significantly increase the size of generated files
• Useful when creating public packages or maintaining API documentation

pipeable #

As an experimental feature, Rabbit can generate pipeable extensions for widgets. This allows you to chain widget properties using this operator (>>) instead of nested constructors.

final widget = $Container()
  >> $Padding(padding: EdgeInsets.all(16))
  >>> Text('Hello, World!');

See this proposal which inspired this feature.

rabbit:
  pipeable: true
  docs: true
  widgets:
    package:flutter/material.dart:
      - Directionality
      - Opacity
      - ClipRRect
      - Transform
      - Padding
      - Align
      - Center
      - SizedBox
      - ConstrainedBox
      - FractionallySizedBox
      - SliverToBoxAdapter
      - Positioned
      - PositionedDirectional
      - Flexible
      - Expanded
      - TableCell
      - GestureDetector
      - DecoratedBox
      - Container
      - Hero
      - Banner
      - PreferredSize
      - InkWell
      - ElevatedButton
      - FilledButton
      - OutlinedButton
      - TextButton
      - FloatingActionButton
      - Tab
      - Card
      - Dialog

Multiple Constructors #

When a widget has multiple constructors, Rabbit generates a separate wrapper for each constructor. For example, with ListView:

// Original ListView has multiple constructors:
// ListView()
// ListView.builder()
// ListView.separated()
// ListView.custom()

// Rabbit will generate:
class $ListView extends StatelessWidget { ... }
class $ListViewBuilder extends StatelessWidget { ... }
class $ListViewSeparated extends StatelessWidget { ... }
class $ListViewCustom extends StatelessWidget { ... }

Each generated wrapper maintains the exact signature and functionality of its corresponding constructor.

Known Limitations #

• Does not support generating wrappers for widgets with private constructors
• Widgets with default values for parameters have those parameters as required in the generated code
• Does not generate imports for types without a prefix

Maintaining Generated Code #

If a Flutter update changes the API of wrapped widgets:

1. Backup your customized wrappers
2. Regenerate the wrappers with the latest Flutter version:

   dart run rabbit generate
   

3. Copy your customizations from the backup to the newly generated files

This ensures your wrappers stay in sync with Flutter's API changes while preserving your modifications.

Common Use Cases #

Theming Widgets #

Create consistent themed versions of widgets across your app:

class PrimaryButton extends StatelessWidget {
  // Generated from ElevatedButton
  // Customized with your theme's primary color
}
### Platform-Specific Variants
```dart
class AdaptiveContainer extends StatelessWidget {
  // Generated from Container
  // Customized with platform-specific styling
}

Adding Default Behaviors #

class LoadingButton extends StatelessWidget {
  // Generated from ElevatedButton
  // Adds loading state handling
}

Best Practices #

When to Use Wrappers #

• For consistent styling across your app
• When you need multiple variants of a widget
• To encapsulate complex behavior

When Not to Use Wrappers #

• For one-off customizations
• When composition would be clearer
• For very simple modifications

Naming Conventions #

• Use descriptive names that indicate the purpose
• Follow Flutter's widget naming conventions
• Consider grouping related wrappers

Complaints #

• Eww, why would you want to do this?
• Why didn't you do it this way?
• Why didn't you use blank instead?
• Why did you do it that way?
• This isn't working, who made this garbage?

You may have a good point, open an issue and let me know.