TButton class

A customizable button widget with multiple variants, sizes, and states.

TButton provides a comprehensive button solution with support for:

  • Multiple visual types (solid, tonal, outline, text, icon)
  • Different sizes (xxs, xs, sm, md, lg, block)
  • Various shapes (normal, pill, circle)
  • Loading states with automatic management
  • Active/toggle states
  • Icons and images
  • Custom theming

Basic Usage

TButton(
  text: 'Click Me',
  icon: HugeIcons.strokeRoundedTick01,
  color: AppColors.primary,
  onTap: () => print('Tapped!'),
)

With Loading State

TButton(
  text: 'Submit',
  loading: true,
  onPressed: (options) async {
    await performAsyncOperation();
    options.stopLoading();
  },
)

Toggle Button

TButton(
  icon: HugeIcons.strokeRoundedFavouriteCircle,
  activeIcon: HugeIcons.strokeRoundedFavourite,
  color: Colors.grey,
  activeColor: Colors.red,
  onChanged: (isActive) => print('Active: $isActive'),
)

See also:

Inheritance
Available extensions

Constructors

TButton({Key? key, TWidgetTheme? baseTheme, TButtonTheme? theme, TButtonShape? shape, TButtonType? type, TButtonSize? size, Color? color, bool loading = false, String loadingText = 'Loading...', ValueNotifier<String>? loadingNotifier, dynamic icon, String? imageUrl, bool forceCache = false, String? text, String? tooltip, VoidCallback? onTap, dynamic onPressed(TButtonPressOptions)?, bool active = false, dynamic activeIcon, Color? activeColor, (double, double)? turns, bool showTick = false, Alignment tickAlignment = Alignment.topRight, Widget? tickWidget, dynamic badge, TSize? badgeSize, Alignment badgeAlignment = Alignment.topRight, Color? badgeColor, Color? badgeTextColor, Widget? child, ValueChanged<bool>? onChanged, Duration duration = const Duration(milliseconds: 400), Duration? throttleDuration, Gradient? gradient, double? elevation, Color? shadowColor, String? semanticLabel, String? semanticIdentifier, Object? permission, TAuthMode? onDenied})
Creates a customizable button widget.
const

Properties

active → bool
Whether the button is in an active state.
final
activeColor → Color?
The color to use when the button is active.
final
activeIcon → dynamic
The icon to display when the button is active.
final
badge → dynamic
An optional badge to display on the button (e.g. notification count, status dot, text, or custom widget).
final
badgeAlignment → Alignment
The alignment of the badge overlay. Defaults to Alignment.topRight.
final
badgeColor → Color?
The background color for the badge. Defaults to AppColors.danger or error theme color.
final
badgeSize → TSize?
The size configuration for the badge. Defaults to null (uses standard badge size).
final
badgeTextColor → Color?
The text color for the badge. Defaults to Colors.white.
final
baseTheme → TWidgetTheme?
The base widget theme to use.
final
child → Widget?
A custom child widget to display in the button.
final
color → Color?
The primary color of the button.
final
duration → Duration
The duration for animations (icon changes, color transitions).
final
elevation → double?
The elevation of the button.
final
forceCache → bool
Whether imageUrl is persistently cached via TImageStorage instead of just Flutter's in-memory ImageCache. See TImage.forceCache.
final
gradient → Gradient?
An optional gradient for the button background.
final
hashCode → int
The hash code for this object.
no setterinherited
icon → dynamic
The icon to display in the button.
final
imageUrl → String?
The URL of an image to display in the button.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loading → bool
Whether to show a loading indicator when onPressed is called.
final
loadingNotifier → ValueNotifier<String>?
An optional notifier to dynamically update the loading message.
final
loadingText → String
The text to display while loading.
final
onChanged → ValueChanged<bool>?
Callback fired when the button's active state changes.
final
onDenied → TAuthMode?
What to do when permission is denied. Null uses the TAuthConfig default (disabled for buttons).
final
onPressed → dynamic Function(TButtonPressOptions)?
Callback fired when the button is pressed with loading state support.
final
onTap → VoidCallback?
Callback fired when the button is tapped.
final
permission → Object?
Permission required to use this button (a String or TPermission), checked against the nearest TAuthScope. Null means no restriction.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticIdentifier → String?
Stable identifier exposed as flt-semantics-identifier on Flutter web for e2e tests.
final
semanticLabel → String?
Accessible label for icon-only buttons. Falls back to tooltip, then text.
final
shadowColor → Color?
Custom shadow color for the button elevation.
final
shape → TButtonShape?
The shape of the button.
final
showTick → bool
Whether to show a checkmark tick when the button is active.
final
size → TSize?
The size configuration for the button.
final
text → String?
The text to display in the button.
final
theme → TButtonTheme?
The theme configuration for this button.
final
throttleDuration → Duration?
The duration to throttle/debounce button taps to prevent duplicate submissions.
final
tickAlignment → Alignment
The alignment of the tick indicator (e.g. top right). Defaults to Alignment.topRight.
final
tickWidget → Widget?
Custom widget to display for the tick indicator.
final
tooltip → String?
The tooltip message to show on hover.
final
turns → (double, double)?
Rotation turns (initial, active) for animation when active state changes. Rotation turns (initial, active) for animation when active state changes.
final
type → TButtonType?
The visual type/variant of the button.
final

Methods

box({double minW = 0.0, double minH = 0.0, double maxW = double.infinity, double maxH = double.infinity}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a ConstrainedBox to apply layout constraints.
card({TCardShadow shadow = TCardShadow.none, EdgeInsetsGeometry padding = const EdgeInsets.all(12), EdgeInsetsGeometry margin = EdgeInsets.zero, BorderRadius? borderRadius, Color? backgroundColor, Color? borderColor, VoidCallback? onTap}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a TCard with a preset shadow depth.
cardLg({EdgeInsetsGeometry padding = const EdgeInsets.all(12), VoidCallback? onTap}) → Widget

Available on Widget, provided by the WidgetX extension

card with a prominent TCardShadow.lg shadow.
cardMd({EdgeInsetsGeometry padding = const EdgeInsets.all(12), VoidCallback? onTap}) → Widget

Available on Widget, provided by the WidgetX extension

card with a standard TCardShadow.md shadow.
cardSm({EdgeInsetsGeometry padding = const EdgeInsets.all(12), VoidCallback? onTap}) → Widget

Available on Widget, provided by the WidgetX extension

card with a subtle TCardShadow.sm shadow.
center({bool when = true}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Center widget.
copyWith({TButtonTheme? theme, TWidgetTheme? baseTheme, TButtonShape? shape, TButtonType? type, TButtonSize? size, dynamic icon, String? imageUrl, Color? color, String? text, bool? loading, String? loadingText, String? tooltip, bool? active, dynamic activeIcon, Color? activeColor, (double, double)? turns, bool? showTick, Alignment? tickAlignment, Widget? tickWidget, dynamic badge, Alignment? badgeAlignment, Color? badgeColor, Color? badgeTextColor, Widget? child, VoidCallback? onTap, dynamic onPressed(TButtonPressOptions)?, ValueChanged<bool>? onChanged, Duration? duration, Duration? throttleDuration, Gradient? gradient, double? elevation, Color? shadowColor, String? semanticLabel, String? semanticIdentifier, Object? permission, TAuthMode? onDenied}) → TButton

Available on TButton, provided by the TButtonExtension extension

Creates a copy of the button with updated properties.
createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<TButton>
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
estimateWidth(BuildContext ctx) → double

Available on TButton, provided by the TButtonWidthX extension

Estimates the width of the button based on its content and size settings.
expanded({int flex = 1}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in an Expanded widget.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
padding([double left = 0.0, double top = 0.0, double right = 0.0, double bottom = 0.0]) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Padding with flexible edge control.
paddingSymmetric({double h = 0.0, double v = 0.0}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Padding with symmetric horizontal and vertical spacing.
size({double? w, double? h}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a SizedBox to apply fixed width and/or height.
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
visible(bool visible, {bool maintainState = false}) → Widget

Available on Widget, provided by the WidgetX extension

Wraps this widget in a Visibility widget.
when(bool condition) → Widget

Available on Widget, provided by the WidgetX extension

Returns this widget if condition is true, otherwise returns SizedBox.shrink(). Usage: Text('Hello').when(isVisible)

Operators

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

Static Methods

custom({required Widget child, VoidCallback? onTap, String? tooltip, dynamic badge, Alignment badgeAlignment = Alignment.topRight, Color? badgeColor, Color? badgeTextColor, double? elevation, Gradient? gradient, Color? shadowColor}) → TButton
Creates a custom button with minimal styling.