MiToggleSwitch

The MiToggleSwitch component is a stateless Flutter widget that renders a toggle switch (on/off switch).

Overview

MiToggleSwitch provides a customizable toggle switch UI element, allowing users to switch between two states (on/off or true/false). Key features include:

• Data binding to a state variable for the toggle value.
• Optional default boolean state.
• Customizable true and false values for data binding.
• Text label for the toggle switch.
• Tile layout option for side-by-side label and switch.
• Configurable active and inactive colors.
• Action invocation on toggle state change.
• JSON configuration for flexible customization.

Component Name: toggleButton

JSON key: "component": "toggleButton".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
value	String	dynamic	Value: State variable key to bind the toggle switch value. The type of value can be dynamic, and is used to determine the toggle state.	null	Yes	No
defaultBoolState	bool	bool	Default Bool State: Initial boolean state of the toggle switch if the value is not yet resolved or is null.	false	Yes	No
trueValue	String	dynamic	True Value: Value to be associated with the 'true' state of the toggle switch when data binding. If provided, along with falseValue, these custom values are used instead of boolean true/false.	null	Yes	No
falseValue	String	dynamic	False Value: Value to be associated with the 'false' state of the toggle switch when data binding. Must be provided along with trueValue to enable custom true/false values.	null	Yes	No
label	String	String	Label: Text label displayed next to or below the toggle switch, providing context.	null	Yes	No
tile	bool	bool	Tile: If true, arranges the label and switch in a horizontal row (tile layout). If false, arranges them in a vertical column.	false	Yes	No
activeColor	String	Color	Active Color: Color of the toggle switch when it is in the 'true' or 'on' state. Can be a theme color key.	green (or theme's green if available)	Yes	No
inactiveColor	String	Color	Inactive Color: Color of the toggle switch when it is in the 'false' or 'off' state. Can be a theme color key.	red (or theme's red if available)	Yes	No
actionName	String	dynamic	Action Name: Name of the action to be invoked when the toggle switch state changes.	null	Yes	No
padding	List<num>	EdgeInsets	Inner Padding: Sets padding within the toggle switch container. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Outer Margin: Defines the margin surrounding the toggle switch widget. Inherited from MiStatelessWidget.	null	Yes	Yes
alignment	String	AlignmentGeometry	Alignment: Specifies how the toggle switch should be aligned within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Background Color: Background color of the toggle switch's container. Inherited from MiStatelessWidget.	null	Yes	No
width	num	double	Fixed Width: Defines a fixed width for the toggle switch component. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Fixed Height: Defines a fixed height for the toggle switch component. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Data Binding Notation: In the example JSON configurations, you will see state variable keys for data binding parameters enclosed in ${} (e.g., "${featureEnabled}"). This notation indicates that the parameter is bound to a state variable within your application's MiCubit. The component will dynamically reflect the value of this state variable and update it when user interaction changes the component's value (if applicable, like with MiToggleSwitch or MiTextField).
• Data Binding: The value parameter enables two-way data binding. The toggle switch's state is linked to the state variable specified by value. Changes in the toggle switch update the state variable, and vice-versa.
• Custom True/False Values: By providing both trueValue and falseValue, you can customize the values associated with the 'true' and 'false' states in your application's data model. If these are not provided, standard boolean true and false are used.
• Action Invocation: The actionName parameter allows you to specify an action to be executed whenever the toggle switch state changes. This is useful for triggering business logic or side effects in response to user toggling the switch.
• Tile Layout: Setting tile to true provides a horizontal layout suitable for settings panels or list tiles where the label is positioned to the left of the switch. tile: false (default) provides a vertical layout with the label below the switch.

Example JSON Configuration

Example 1: Basic Toggle Switch with Label and Data Binding

{
  "component": "toggleButton",
  "label": "Enable Feature",
  "value": "${featureEnabled}"
}

Explanation of Example 1:

• This example creates a basic toggle switch with the label "Enable Feature".
• "component": "toggleButton" identifies this as a MiToggleSwitch component.
• "label": "Enable Feature" sets the text label for the toggle switch.
• "value": "${featureEnabled}" binds the toggle switch's boolean state to the state variable featureEnabled. The state variable ${featureEnabled} will hold true when the switch is on and false when off. Note the use of ${} to indicate data binding.

Example 2: Toggle Switch with Custom True/False Values

{
  "component": "toggleButton",
  "label": "Notification Preference",
  "value": "${notificationSetting}",
  "trueValue": "ALLOW",
  "falseValue": "DENY"
}

Explanation of Example 2:

• This example demonstrates using custom values instead of boolean true/false.
• "trueValue": "ALLOW" sets the value associated with the 'on' state to the string "ALLOW".
• "falseValue": "DENY" sets the value associated with the 'off' state to the string "DENY".
• "value": "${notificationSetting}" binds the toggle state to the notificationSetting state variable. ${notificationSetting} will hold either "ALLOW" or "DENY" based on the toggle switch state. Note the use of ${} for data binding.

Example 3: Toggle Switch in Tile Layout with Action

{
  "component": "toggleButton",
  "label": "Dark Mode",
  "tile": true,
  "value": "${darkModeEnabled}",
  "actionName": "toggleDarkMode"
}

Explanation of Example 3:

• This example shows a toggle switch configured for tile layout and action invocation.
• "tile": true arranges the label "Dark Mode" horizontally next to the switch.
• "actionName": "toggleDarkMode" specifies that the action named toggleDarkMode should be executed whenever the toggle switch state changes. This action could be defined in your MiCubit to handle the logic for enabling or disabling dark mode in the application.
• "value": "${darkModeEnabled}" binds the state to the darkModeEnabled state variable. Note the use of ${} for data binding.

Example 4: Toggle Switch with Custom Colors

{
  "component": "toggleButton",
  "label": "High Contrast",
  "activeColor": "accentColor",
  "inactiveColor": "grey",
  "value": "${highContrastEnabled}"
}

Explanation of Example 4:

• This example demonstrates customizing the colors of the toggle switch.
• "activeColor": "accentColor" sets the color of the switch in the 'on' state to the color defined by the theme key "accentColor".
• "inactiveColor": "grey" sets the color of the switch in the 'off' state to the color defined by the theme key "grey".
• "value": "${highContrastEnabled}" binds the state to the ${highContrastEnabled} state variable. Note the use of ${} for data binding.