MiButton

The MiButton component is a versatile Flutter widget for creating interactive buttons with rich styling and action capabilities. Configuration is driven by JSON, allowing for dynamic and declarative button definitions.

Overview

MiButton is a cornerstone component for user interaction in your Flutter application, built upon the foundation of MiStatelessWidget. It is specifically engineered to seamlessly integrate with the MiAction architecture, enabling buttons to trigger complex application logic, navigation, and data manipulations. Beyond basic button functionality, MiButton offers a range of visual styles through button types (filled, outlined, text, elevated, tonal) and extensive customization options for labels, icons, size, shape, and colors—all configurable via JSON.

Component Name: button

JSON key: "component": "button".

MiButton Parameters

The MiButton component is highly customizable through the following JSON parameters. These parameters encompass button-specific settings and styling options inherited from the MiStatelessWidget base class:

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
action	dynamic	dynamic	Button Action Configuration: This is the most critical parameter, defining the action executed when the button is tapped. It should be structured as a JSON object that specifies an actionType and associated parameters recognized by your application's action system. For instance, to navigate to a new page, you would use an actionType like "navigate" (handled by NavigationAction). If action is omitted, the button will be rendered visually but will not respond to taps.	None (Button renders as non-interactive if not provided)	Yes	No
label	dynamic	Widget	Button Label Content: Specifies the widget to display as the button's primary text label. This parameter can accept a simple String for default text styling or a JSON configuration for a MiText component for richer text formatting. This allows for rich text formatting and dynamic content within the button label.	None (Button renders without a label if not provided)	Yes	Yes
icon	dynamic	Widget	Leading Icon: Defines an optional icon to be displayed at the leading edge of the button, preceding the label. This parameter usually takes a JSON configuration for a MiIcon component, enabling the use of vector icons from various icon packages.	None (Button renders without an icon if not provided)	Yes	Yes
type	String	String	Visual Button Type: Determines the fundamental visual style of the button, influencing its default appearance. Valid values are: "filled", "outlined", "text", "elevated", and "tonal". Each type corresponds to a Material Design button style, providing pre-defined defaults for background color, border, and text/icon colors, which can be further customized.	"filled"	Yes	Yes
borderRadius	double	double	Corner Radius: Sets the border radius for the button's corners, controlling the degree of roundness. A larger value results in more rounded corners.	Dynamically determined by the large parameter and button type; defaults to 80 for standard-size buttons and 16 for large buttons.	Yes	No
large	bool	bool	Large Button Variant: A boolean flag that, when set to true, instructs the MiButton to render in a larger, more prominent size. This impacts several default styling attributes, including padding, text and icon sizes, and border radius, enhancing touchability and visual emphasis, especially for primary actions.	false	Yes	No
borderColor	String	Color	Border Color: Specifies the color of the button's border. This parameter is most visually significant for the "outlined" button type, but can be applied to others for custom border styling. Accepts standard Flutter color names or hexadecimal color codes.	Context-dependent, varying with button type and the application's theme. Defaults to transparent for most types, and the theme's accent color for the "outlined" type.	Yes	No
color	String	Color	Background or Foreground Color: Sets the button's background fill color. For "outlined" and "text" types, this parameter primarily affects the color of the button's label and icon, as these types typically have transparent backgrounds. Accepts Flutter color names or hex codes.	Context-dependent, varying with button type and application theme. Defaults to the theme's accent color for "filled" and transparent for "outlined" and "text" types.	Yes	No
width	num (Number)	double	Fixed Width: Defines a fixed width for the button component. If not specified, the button will size itself to its content (intrinsic width).	None (Intrinsic width)	Yes	No
height	num (Number)	double	Fixed Height: Defines a fixed height for the button component. If not specified, the button will size itself to its content (intrinsic height).	None (Intrinsic height)	Yes	No
padding	List<num>	EdgeInsets	Inner Padding: Sets the padding within the button, around the combined area of the label and icon. This parameter expects a list of numerical values representing padding. The list can specify all four sides ([left, top, right, bottom]), horizontal and vertical ([horizontal, vertical]), or uniform padding on all sides ([all]).	Dynamically calculated based on label, icon presence, large size, and type to ensure consistent and visually appealing button layouts across different configurations.	Yes	No
margin	List<num>	EdgeInsets	Outer Margin: Defines the margin surrounding the entire button widget, controlling the spacing between the button and neighboring UI elements. Like padding, it accepts a numerical list for specifying margin values in [left, top, right, bottom], [horizontal, vertical], or [all] formats.	None	Yes	No
alignment	String	AlignmentGeometry	Alignment within Parent: Specifies how the button should be positioned or aligned within its parent layout container. Uses Flutter's AlignmentGeometry system, accepting keywords like 'topLeft', 'center', 'bottomRight', etc. Refer to Flutter's comprehensive Alignment documentation for available options.	"topLeft"	Yes	No

Note:

• Action-Driven Interactivity: MiButton is fundamentally action-oriented. The action parameter is paramount; it dictates the button's interactive behavior and how it integrates with your application's logic flow via MiAction. Without a defined action, the button becomes a purely visual element.
• Inheritance from MiStatelessWidget: Styling and layout fundamentals are inherited from MiStatelessWidget. Parameters like color, alignment, width, height, padding, and margin provide the base for controlling the button's visual properties and placement within its parent widget.
• Styling Versatility: MiButton offers extensive styling options through parameters such as type, borderRadius, borderColor, and color, enabling developers to create buttons that conform to diverse design requirements and Material Design specifications.
• Content Richness with Labels and Icons: The label and icon parameters empower developers to embed rich content within buttons. By utilizing MiText and MiIcon JSON configurations, you can easily integrate styled text and vector icons, significantly enhancing button usability and visual communication.
• Action Resolution Process: When a MiButton is tapped, the action JSON configuration is processed by the application's action system. This system resolves and executes the specified action. This resolution process typically involves identifying the actionType (e.g., "navigate") and invoking the corresponding MiAction processor (e.g., NavigationAction) to perform the desired operation, such as page navigation, API calls, or state updates.

Example JSON Configurations

Example 1: Simple Submit Button with String Label

{
  "component": "button",
  "type": "filled",
  "label": "Submit",
  "large": false,
  "color": "primary",
  "action": {
    "actionType": "validateForm"
  }
}

Explanation of Example 1:

• component: "button": Identifies this as a MiButton component.
• type: "filled": Creates a prominent filled button.
• label: "Submit": Sets the button label to "Submit". Note: Here, label is a simple string, resulting in default text styling.
• large: false: Renders the button in its standard size.
• color: "primary": Applies the theme's primary color.
• action: Defines the button's action on tap as "validateForm".

Example 2: Detailed Settings Button with MiText Label and Navigation Type

{
  "component": "button",
  "type": "outlined",
  "label": {
    "component": "text",
    "text": "App Settings",
    "size": 16,
    "weight": 600,
    "color": "blueGrey"
  },
  "icon": "settings",
  "color": "accent",
  "borderRadius": 24,
  "padding": [12, 24],
  "action": {
    "actionType": "navigate",
    "navigationType": "push",
    "pageName": "settingsPage"
  }
}

Explanation of Example 2:

• component: "button": Identifies this as a MiButton component.
• type: "outlined": Creates an outlined button style.
• label: Configures the button's label using a MiText component for detailed styling.
  • component: "text": Specifies the use of a MiText component for rich text.
  • text: "App Settings": Sets the label text to "App Settings".
  • size: 16: Sets the font size to 16.
  • weight: 600: Sets the font weight to semi-bold (600).
  • color: "blueGrey": Sets the text color to "blueGrey".
• icon: "settings": Adds a "settings" icon.
• color: "accent": Uses the theme's accent color for visual consistency.
• borderRadius: 24: Sets a larger border radius for rounded corners.
• padding: [12, 24]: Customizes padding.
• action: Defines the button's action as navigation to "settingsPage".
  • actionType: "navigate": Specifies a navigation action.
  • navigationType: "push": Indicates a "push" navigation, adding the settings page to the navigation stack.
  • pageName: "settingsPage": Specifies the target page as "settingsPage".