ShadButton class

A highly customizable button widget with variant and size options.

The ShadButton widget provides a flexible button with multiple styling variants (primary, destructive, outline, secondary, ghost, link) and sizes (regular, small, large). It supports rich interaction states (hover, press, focus) and can include leading/trailing widgets alongside text. Use named constructors for specific variants or ShadButton.raw for full control.

Inheritance
Available extensions

Constructors

ShadButton({Key? key, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, ShadButtonSize? size, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates a primary variant button widget.
const
ShadButton.destructive({Key? key, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, ShadButtonSize? size, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates a destructive variant button widget, typically for warning or error actions.
const
ShadButton.ghost({Key? key, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, ShadButtonSize? size, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates a ghost variant button widget, typically with minimal styling.
const
Creates a link variant button widget, styled like a hyperlink.
const
ShadButton.outline({Key? key, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, ShadButtonSize? size, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates an outline variant button widget, typically with a bordered appearance.
const
ShadButton.raw({Key? key, required ShadButtonVariant variant, ShadButtonSize? size, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates a button widget with a specified variant, allowing full control over configuration.
const
ShadButton.secondary({Key? key, Widget? child, Widget? leading, Widget? trailing, VoidCallback? onPressed, ShadButtonSize? size, MouseCursor? cursor, double? width, double? height, EdgeInsetsGeometry? padding, Color? backgroundColor, Color? hoverBackgroundColor, Color? foregroundColor, Color? hoverForegroundColor, bool autofocus = false, FocusNode? focusNode, Color? pressedBackgroundColor, Color? pressedForegroundColor, List<BoxShadow>? shadows, Gradient? gradient, TextDecoration? textDecoration, TextDecoration? hoverTextDecoration, ShadDecoration? decoration, bool enabled = true, VoidCallback? onLongPress, ShadStatesController? statesController, MainAxisAlignment? mainAxisAlignment, CrossAxisAlignment? crossAxisAlignment, ShadHoverStrategies? hoverStrategies, ValueChanged<bool>? onHoverChange, ValueChanged<TapDownDetails>? onTapDown, ValueChanged<TapUpDetails>? onTapUp, VoidCallback? onTapCancel, ValueChanged<TapDownDetails>? onSecondaryTapDown, ValueChanged<TapUpDetails>? onSecondaryTapUp, VoidCallback? onSecondaryTapCancel, ValueChanged<LongPressStartDetails>? onLongPressStart, VoidCallback? onLongPressCancel, VoidCallback? onLongPressUp, ValueChanged<LongPressDownDetails>? onLongPressDown, ValueChanged<LongPressEndDetails>? onLongPressEnd, VoidCallback? onDoubleTap, ValueChanged<TapDownDetails>? onDoubleTapDown, VoidCallback? onDoubleTapCancel, Duration? longPressDuration, TextDirection? textDirection, double? gap, ValueChanged<bool>? onFocusChange, bool? expands, TextStyle? textStyle, bool? canRequestFocus})
Creates a secondary variant button widget, typically for less prominent actions.
const

Properties

autofocus → bool
Whether the button should automatically receive focus when the widget is built. Defaults to false; managed by focusNode.
final
backgroundColor → Color?
The background color of the button when not hovered or pressed, overriding the theme default if provided. Changes based on variant if not explicitly set.
final
canRequestFocus → bool?
Whether the button can request focus. Defaults to true if enabled is true, false otherwise.
final
child → Widget?
The main content widget of the button, typically a Text widget. Styled with the foreground color and theme text styles.
final
crossAxisAlignment → CrossAxisAlignment?
The cross axis alignment of the button's content within its Row. Defaults to CrossAxisAlignment.center if not specified.
final
cursor → MouseCursor?
The mouse cursor displayed over the button, overriding the theme default if specified. Typically SystemMouseCursors.click when enabled.
final
decoration → ShadDecoration?
Custom decoration for the button, merged with theme defaults if provided. Allows advanced styling beyond basic colors and shadows.
final
enabled → bool
Whether the button is interactive, defaults to true. If false, the button is disabled, visually dimmed, and non-responsive.
final
expands → bool?
Whether the child expands to fill available space along the main axis. Defaults to false if not specified.
final
focusNode → FocusNode?
The focus node for keyboard navigation, created internally if not provided. Enables focus handling and shortcuts like Enter key activation.
final
foregroundColor → Color?
The color of the button's content (e.g., text, icons) when not hovered or pressed. Overrides the theme default if provided; required in theme if not set.
final
gap → double?
The gap between the button's items (e.g., leading, child, trailing). Defaults to 8 pixels if not specified.
final
gradient → Gradient?
The gradient applied to the button's background, overriding the theme default if provided. Supersedes backgroundColor if both are set.
final
hashCode → int
The hash code for this object.
no setterinherited
height → double?
The explicit minimum height of the button, overriding size-based defaults. If null, it falls back to theme or size-specific minimums. When set to 0, or a value smaller than the child's height the button's height will be determined by its child.
final
hoverBackgroundColor → Color?
The background color of the button when hovered, overriding the theme default if provided. Applied during mouse hover for visual feedback.
final
hoverForegroundColor → Color?
The color of the button's content when hovered, overriding the theme default if provided. Applied during mouse hover for visual feedback.
final
hoverStrategies → ShadHoverStrategies?
The strategies for handling hover behavior, overriding the theme default if provided. Controls how hover states are detected and applied.
final
hoverTextDecoration → TextDecoration?
The text decoration applied to the button's text when hovered, overriding the theme default if provided. Applied during mouse hover for visual feedback.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
leading → Widget?
The widget displayed before the main child, typically an icon or small graphic. Positioned according to mainAxisAlignment and textDirection.
final
longPressDuration → Duration?
The duration required to trigger a long press, overriding the theme default if provided. Controls the timing of onLongPress and related callbacks.
final
mainAxisAlignment → MainAxisAlignment?
The main axis alignment of the button's content within its Row. Defaults to MainAxisAlignment.center if not specified.
final
onDoubleTap → VoidCallback?
Callback invoked when a double tap occurs. For advanced gesture handling.
final
onDoubleTapCancel → VoidCallback?
Callback invoked when a double tap is canceled. For advanced gesture handling.
final
onDoubleTapDown → ValueChanged<TapDownDetails>?
Callback invoked when a double tap begins, providing details. For advanced gesture handling.
final
onFocusChange → ValueChanged<bool>?
Callback invoked when the focus state changes, providing the new focus value. Complements internal focus state management.
final
onHoverChange → ValueChanged<bool>?
Callback invoked when the hover state changes, providing the new hover value. Complements internal hover state management.
final
onLongPress → VoidCallback?
The callback invoked when the button is long-pressed, adding long-press functionality if provided. Controlled by longPressDuration for timing.
final
onLongPressCancel → VoidCallback?
Callback invoked when a long press is canceled. Part of long-press gesture handling.
final
onLongPressDown → ValueChanged<LongPressDownDetails>?
Callback invoked when a long press is detected, providing details. Part of long-press gesture handling.
final
onLongPressEnd → ValueChanged<LongPressEndDetails>?
Callback invoked when a long press ends, providing details. Part of long-press gesture handling.
final
onLongPressStart → ValueChanged<LongPressStartDetails>?
Callback invoked when a long press begins, providing details. Part of long-press gesture handling.
final
onLongPressUp → VoidCallback?
Callback invoked when a long press ends by lifting. Part of long-press gesture handling.
final
onPressed → VoidCallback?
The callback invoked when the button is tapped.
final
onSecondaryTapCancel → VoidCallback?
Callback invoked when a secondary tap is canceled. For advanced gesture handling.
final
onSecondaryTapDown → ValueChanged<TapDownDetails>?
Callback invoked when a secondary (e.g., right-click) tap begins, providing tap details. For advanced gesture handling.
final
onSecondaryTapUp → ValueChanged<TapUpDetails>?
Callback invoked when a secondary tap ends, providing tap details. For advanced gesture handling.
final
onTapCancel → VoidCallback?
Callback invoked when a tap is canceled. Resets the pressed state.
final
onTapDown → ValueChanged<TapDownDetails>?
Callback invoked when a tap begins, providing tap details. Triggers the pressed state visually.
final
onTapUp → ValueChanged<TapUpDetails>?
Callback invoked when a tap ends, providing tap details. Ends the pressed state visually.
final
padding → EdgeInsetsGeometry?
Padding around the button's content, overriding size-based defaults if specified. Controls internal spacing within the button.
final
pressedBackgroundColor → Color?
The background color of the button when pressed, overriding the theme default if provided. Applied during tap or long-press interactions.
final
pressedForegroundColor → Color?
The foreground color of the button when pressed, overriding the theme default if provided. Applied to content during tap or long-press interactions.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shadows → List<BoxShadow>?
The list of box shadows applied to the button, overriding the theme default if provided. Enhances visual depth and elevation.
final
size → ShadButtonSize?
The size of the button, one of ShadButtonSize options (regular, sm, lg). Affects dimensions and padding unless overridden by width, height, or padding.
final
statesController → ShadStatesController?
The controller for managing button states (e.g., hovered, pressed, focused). If null, an internal controller is created.
final
textDecoration → TextDecoration?
The text decoration applied to the button's text when not hovered, overriding the theme default if provided. E.g., TextDecoration.underline for styling.
final
textDirection → TextDirection?
The text direction for the button's content, overriding the default if specified. Can be set to TextDirection.ltr or TextDirection.rtl.
final
textStyle → TextStyle?
The text style applied to the button's child when it is a Text widget, overriding the theme default if provided. Allows customization of font size, weight, and other text properties.
final
trailing → Widget?
The widget displayed after the main child, typically an icon or small graphic. Positioned according to mainAxisAlignment and textDirection.
final
variant → ShadButtonVariant
The variant of the button, one of ShadButtonVariant options (primary, destructive, etc.). Determines the visual style applied through the ShadTheme.
final
width → double?
The explicit minimum width of the button, overriding size-based defaults. If null, it falls back to theme or size-specific minimums. When set to 0, or a value smaller than the child's width the button's width will be determined by its child.
final

Methods

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).
createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ShadButton>
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
positionedWith(ShadPosition position) → Widget

Available on Widget, provided by the PositionedExt extension

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