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
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
colorFilter([ColorFilter? colorFilter]) → Widget: Available on Widget, provided by the GenericExtensions extension
set parent widget in center
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
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
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

Operators

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