ModalBuilder class

A widget that shows modals with hot reload support

This is the recommended way to show modals in your app. It provides:

Hot reload support during development
Clean, declarative API with minimal boilerplate
Automatic builder registration and cleanup

When to use `ModalBuilder` vs `Modal.show()`

Use Case	Approach
Button/tap triggers modal	`ModalBuilder` ✅
Programmatic/conditional showing	`Modal.show()`
Modal replacement	`Modal.show()`
Reactive content with state management	`Modal.show()` with reactive wrapper

Basic Usage

You can pass either a Widget directly or a builder function:

// With a widget directly (simpler)
ModalBuilder(
  content: MyModalContent(),
  child: ElevatedButton(child: Text('Show Modal')),
)

// With a builder function (for complex content)
ModalBuilder(
  builder: () => MyModalContent(),
  child: ElevatedButton(child: Text('Show Modal')),
)

Bottom Sheet (default)

ModalBuilder(
  content: MyContent(),
  height: 300,
  shouldBlurBackground: true,
  child: MyButton(),
)

Dialog

ModalBuilder.dialog(
  content: MyDialogContent(),
  shouldBlurBackground: true,
  child: MyButton(),
)

With Callbacks

ModalBuilder(
  content: MyContent(),
  onPressed: () => print('Opening modal'),
  onDismissed: () => print('Modal closed'),
  child: MyButton(),
)

Inheritance

Available extensions

Constructors

ModalBuilder({Key? key, ModalWidgetBuilder? builder, required Widget child, bool shouldBlurBackground = false, double blurAmount = 3.0, Function? onDismissed, Function? onExpanded, ModalType modalType = ModalType.sheet, Alignment modalPosition = Alignment.bottomCenter, ModalAnimationType modalAnimationType = ModalAnimationType.fade, bool isDismissable = true, bool isDraggable = false, bool isExpandable = false, double? size, double expandedPercentageSize = 85, double contentPaddingByDragHandle = 35.0, bool isSwipeable = true, Duration? autoDismissDuration, SnackbarDisplayMode snackbarDisplayMode = SnackbarDisplayMode.staggered, int maxStackedSnackbars = 3, Color? modalColor, Color barrierColor = Colors.transparent, bool blockBackgroundInteraction = false, double? snackbarWidth, String? id}): Creates a ModalBuilder for bottom sheet modals (default)
const
ModalBuilder.bottomSheet({Key? key, ModalWidgetBuilder? builder, required Widget child, bool shouldBlurBackground = false, double blurAmount = 3.0, Function? onDismissed, Function? onExpanded, bool isDismissable = true, bool isExpandable = false, double? size, double expandedPercentageSize = 85, double contentPaddingByDragHandle = 35.0, Color? modalColor, Color barrierColor = Colors.transparent, bool blockBackgroundInteraction = false, String? id}): Creates a ModalBuilder for bottom sheet modals
const
ModalBuilder.dialog({Key? key, ModalWidgetBuilder? builder, required Widget child, bool shouldBlurBackground = true, double blurAmount = 3.0, Function? onDismissed, bool isDismissable = true, bool isDraggable = false, double? size, Alignment modalPosition = Alignment.center, ModalAnimationType modalAnimationType = ModalAnimationType.fade, Color barrierColor = Colors.transparent, bool blockBackgroundInteraction = false, String? id}): Creates a ModalBuilder for dialog modals
const
ModalBuilder.snackbar({Key? key, ModalWidgetBuilder? builder, required Widget child, bool shouldBlurBackground = false, double blurAmount = 3.0, Function? onDismissed, bool isDismissable = true, double? size, Alignment modalPosition = Alignment.bottomCenter, ModalAnimationType modalAnimationType = ModalAnimationType.slide, bool isSwipeable = true, Duration? autoDismissDuration = const Duration(seconds: 4), SnackbarDisplayMode snackbarDisplayMode = SnackbarDisplayMode.replace, int maxStackedSnackbars = 3, Color barrierColor = Colors.transparent, bool blockBackgroundInteraction = false, double? snackbarWidth, String? id}): Creates a ModalBuilder for snackbar modals
const

Properties

autoDismissDuration → Duration?: Auto-dismiss duration for snackbars (null means no auto-dismiss)
final
barrierColor → Color: The color of the background dismiss overlay
final
blockBackgroundInteraction → bool: Whether to block all tap interactions with the background content
final
blurAmount → double: The intensity of the blur effect (0.0 to 20.0, default: 3.0)
final
builder → ModalWidgetBuilder?: Builder function that creates the modal content widget
final
child → Widget: The child widget - typically a button that triggers the modal Tapping this widget will automatically show the modal.
final
contentPaddingByDragHandle → double: Padding on the side where the drag handle is located
final
expandedPercentageSize → double: Maximum expanded size as percentage of screen dimension (0-100)
final
hashCode → int: The hash code for this object.
no setterinherited
id → String?: Optional ID for programmatic dismissal and tracking ent Allows you to dismiss a specific modal by ID. If not provided, a unique ID will be auto-generated.
final
isDismissable → bool: Whether the modal can be dismissed by the user
final
isDraggable → bool: Whether the modal can be dragged by the user (for dialogs)
final
isExpandable → bool: Whether the sheet can be expanded by dragging (for sheets)
final
isSwipeable → bool: Whether the snackbar can be swiped to dismiss (snackbars only)
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
makeRefreshable → Widget: Available on Widget?, provided by the WidgetExtension extension
Make your any widget refreshable with RefreshIndicator on top
no setter
maxStackedSnackbars → int: Maximum stacked snackbars visible at once
final
modalAnimationType → ModalAnimationType: Animation style for entry/exit
final
modalColor → Color?: Optional background color for the bottom sheet
final
modalPosition → Alignment: Position of the modal on screen
final
modalType → ModalType: The type of modal (bottomSheet, dialog, etc.)
final
onDismissed → Function?: Callback when the modal is dismissed
final
onExpanded → Function?: Callback when a bottom sheet is expanded
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shouldBlurBackground → bool: Whether to apply a blur effect to content behind the modal
final
size → double?: The initial size of the sheet (height for bottom/top, width for side sheets)
final
snackbarDisplayMode → SnackbarDisplayMode: How multiple snackbars are displayed
final
snackbarWidth → double?: Width of the snackbar (percentage of screen width, 0-1)
final

Methods

addMaterialWidget() → Material: Available on Widget, provided by the GenericExtensions extension
addTooltipWidget(String toolTip) → Tooltip: Available on Widget, provided by the GenericExtensions extension
animate({Key? key, List<Effect>? effects, AnimateCallback? onInit, AnimateCallback? onPlay, AnimateCallback? onComplete, bool? autoPlay, Duration? delay, AnimationController? controller, Adapter? adapter, double? target, double? value}) → Animate: Available on Widget, provided by the AnimateWidgetExtensions extension
Wraps the target Widget in an Animate instance, and returns the instance for chaining calls. Ex. myWidget.animate() is equivalent to Animate(child: myWidget).
borderRadius([BorderRadiusGeometry? borderRadius]) → Widget: Available on Widget, provided by the GenericExtensions extension
boxDecoration([BoxDecoration? boxDecoration]) → Widget: Available on Widget, provided by the GenericExtensions extension
center({double? heightFactor, double? widthFactor}) → Widget: Available on Widget?, provided by the WidgetExtension extension
set parent widget in center
colorFilter([ColorFilter? colorFilter]) → Widget: Available on Widget, provided by the GenericExtensions extension
set parent widget in center
cornerRadiusWithClipRRect(double radius) → ClipRRect: Available on Widget?, provided by the WidgetExtension extension
add corner radius
cornerRadiusWithClipRRectOnly({int bottomLeft = 0, int bottomRight = 0, int topLeft = 0, int topRight = 0}) → ClipRRect: Available on Widget?, provided by the WidgetExtension extension
add custom corner radius each side
createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ModalBuilder>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
expand({int flex = 1}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add Expanded to parent widget
fit({BoxFit? fit, AlignmentGeometry? alignment}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add FittedBox to parent widget
flexible({int flex = 1, FlexFit? fit}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add Flexible to parent widget
launch<T>(BuildContext context, {bool isNewTask = false, PageRouteAnimation? pageRouteAnimation, Duration? duration, String? routeName, Object? routeArguments}) → Future<T?>: Available on Widget?, provided by the WidgetExtension extension
Launch a new screen
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onTap(Function? function, {BorderRadius? borderRadius, Color? splashColor, Color? hoverColor, Color? highlightColor, Color? focusColor, WidgetStateProperty<Color?>? overlayColor}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add tap to parent widget
opacity({required double opacity, int durationInSecond = 1, Duration? duration}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add opacity to parent widget
paddingAll(double padding) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding all
paddingBottom(double bottom) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding bottom
paddingDirectional({double start = 0.0, double top = 0.0, double end = 0.0, double bottom = 0.0}) → Widget: Available on Widget?, provided by the WidgetExtension extension
paddingLeft(double left) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding left
paddingOnly({double top = 0.0, double left = 0.0, double bottom = 0.0, double right = 0.0}) → Padding: Available on Widget?, provided by the WidgetExtension extension
return custom padding from each side
paddingRight(double right) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding right
paddingSymmetric({double vertical = 0.0, double horizontal = 0.0}) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding symmetric
paddingTop(double top) → Padding: Available on Widget?, provided by the WidgetExtension extension
return padding top
rotate({required double angle, bool transformHitTests = true, Offset? origin}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add rotation to parent widget
scale({required double scale, Offset? origin, AlignmentGeometry? alignment, bool transformHitTests = true}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add scaling to parent widget
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
tooltip({required String msg}) → Widget: Available on Widget?, provided by the WidgetExtension extension
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited
translate({required Offset offset, bool transformHitTests = true, Key? key}) → Widget: Available on Widget?, provided by the WidgetExtension extension
add translate to parent widget
validate({Widget value = const SizedBox()}) → Widget: Available on Widget?, provided by the WidgetExtension extension
Validate given widget is not null and returns given value if null.
visible(bool visible, {Widget? defaultWidget}) → Widget: Available on Widget?, provided by the WidgetExtension extension
set visibility
withHeight(double height) → SizedBox: Available on Widget?, provided by the WidgetExtension extension
With custom height
withRoundedCorners({Color backgroundColor = whiteColor, BorderRadius borderRadius = const BorderRadius.all(Radius.circular(8.0)), LinearGradient? gradient, BoxBorder? border, List<BoxShadow>? boxShadow, DecorationImage? decorationImage, BoxShape boxShape = BoxShape.rectangle}) → Container: Available on Widget?, provided by the WidgetExtension extension
withScroll({ScrollPhysics? physics, EdgeInsetsGeometry? padding, Axis scrollDirection = Axis.vertical, ScrollController? controller, DragStartBehavior dragStartBehavior = DragStartBehavior.start, bool? primary, required bool reverse}) → Widget: Available on Widget?, provided by the WidgetExtension extension
withShaderMask(List<Color> colors, {BlendMode blendMode = BlendMode.srcATop}) → Widget: Available on Widget?, provided by the WidgetExtension extension
Wrap with ShaderMask widget
withShaderMaskGradient(Gradient gradient, {BlendMode blendMode = BlendMode.srcATop}) → Widget: Available on Widget?, provided by the WidgetExtension extension
Wrap with ShaderMask widget Gradient
withShadow({Color bgColor = whiteColor, Color shadowColor = Colors.black12, dynamic blurRadius = 10.0, dynamic spreadRadius = 0.0, Offset offset = const Offset(0.0, 0.0), LinearGradient? gradient, BoxBorder? border, DecorationImage? decorationImage, BoxShape boxShape = BoxShape.rectangle}) → Container: Available on Widget?, provided by the WidgetExtension extension
withSize({double width = 0.0, double height = 0.0}) → SizedBox: Available on Widget?, provided by the WidgetExtension extension
With custom height and width
withTooltip({required String msg}) → Widget: Available on Widget?, provided by the WidgetExtension extension
Validate given widget is not null and returns given value if null.
withVisibility(bool visible, {Widget? replacement, bool maintainAnimation = false, bool maintainState = false, bool maintainSize = false, bool maintainSemantics = false, bool maintainInteractivity = false}) → Visibility: Available on Widget?, provided by the WidgetExtension extension
set widget visibility
withWidth(double width) → SizedBox: Available on Widget?, provided by the WidgetExtension extension
With custom width

Operators

operator ==(Object other) → bool: The equality operator.
inherited