MiDropDown

The MiDropDown component is a stateful Flutter widget for creating dropdown selection fields. It supports single and multi-select modes, dynamic item loading from API or static lists, and various styling options, all configurable via JSON.

Overview

MiDropDown provides a versatile dropdown input field for Flutter applications. It leverages the dropdown_search package to offer features like searching within dropdown items and multi-selection. Items can be provided as a static list within the JSON configuration or loaded dynamically from an API endpoint. The appearance and behavior of the dropdown are highly customizable through JSON parameters.

Component Name: dropdown

JSON key: "component": "dropdown".

Parameters

The MiDropDown component is highly customizable with these JSON parameters, in addition to the base styling parameters inherited from MiStatelessWidget:

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
value	dynamic	dynamic	Initial Value: Sets the initial selected value(s) for the dropdown. Can be a single value for single-select or a list of values for multi-select. Data type depends on the itemValueKey. Supports state variable resolution using the $ symbol (e.g., "${USER.SELECTED_ROLE}").	null	Yes	No
label	String	String	Label Text: Text displayed as the label for the dropdown. Supports state variable resolution using the $ symbol (e.g., "${LABELS.ROLE}").	null	Yes	No
labelBehavior	String	String	Label Behavior: Defines how the label is displayed. Options: "hide", "separate", "inline", "top".	"inline"	Yes	No
fontSize	num	double	Font Size: Font size for the label and dropdown items.	15.0	Yes	No
fillColor	String	Color	Fill Color: Background color of the dropdown input field. Accepts Flutter color names or hex codes.	null	Yes	No
borderRadius	num	double	Border Radius: Corner radius of the dropdown input field.	8.0	Yes	No
borderColor	String	Color	Border Color: Color of the border when the dropdown is not focused. Accepts Flutter color names or hex codes. Defaults to theme's "outline" color or Colors.black.	"outline" or Colors.black	Yes	No
focusBorderColor	String	Color	Focus Border Color: Color of the border when the dropdown is focused. Accepts Flutter color names or hex codes. Defaults to theme's "accent" color or Colors.black.	"accent" or Colors.black	Yes	No
isRequired	bool	bool	Required: If true, a validation error is shown if no item is selected (or no items in multi-select).	false	Yes	No
searchable	bool	bool	Searchable: If true, enables a search box in the dropdown popup to filter items.	false	Yes	No
multiSelect	bool	bool	Multi-Select: If true, allows multiple items to be selected. If false, single selection mode is enabled.	false	Yes	No
items	List	List<dynamic>	Static Items List: A static list of items for the dropdown. Can be a list of primitives (String, Number) or a list of Maps. If maps are used, itemValueKey and itemDisplayKey are required.	null	Yes	No
apiForItems	Map	Map	API for Items: JSON configuration for an API call to dynamically fetch dropdown items. See "API Configuration for Items" note below.	null	Yes	No
itemValueKey	String	String	Item Value Key: Key to extract the value from each item in items or API response (when items are maps). Required if items or API response is a list of maps. Supports state variable resolution using the $ symbol (e.g., "${ITEM.ID}").	null	Yes	No
itemDisplayKey	String	String	Item Display Key: Key to extract the display text from each item in items or API response (when items are maps). Required if items or API response is a list of maps. Supports state variable resolution using the $ symbol (e.g., "${ITEM.NAME}").	null	Yes	No
onChangedAction	dynamic	dynamic	On Changed Action: Action to be executed when the selected value changes. JSON object with actionType and parameters.	null	Yes	No
uniqueId	String	String	Unique ID: A unique identifier for the dropdown. Used for state management and keying.	null	Yes	No
padding	List<num>	EdgeInsets	Inner Padding: Sets padding within the dropdown container. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Outer Margin: Defines the margin surrounding the dropdown widget. Inherited from MiStatelessWidget.	null	Yes	No
alignment	String	AlignmentGeometry	Alignment: Specifies how the dropdown should be aligned within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Background Color: Background color of the dropdown container. Inherited from MiStatelessWidget.	null	Yes	No
width	num	double	Fixed Width: Defines a fixed width for the dropdown component. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Fixed Height: Defines a fixed height for the dropdown component. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Data Sources: Dropdown items can be provided statically using the items parameter or dynamically fetched from an API using the apiForItems parameter. Only one of these should be configured.
• Item Keys: When items or apiForItems return a list of maps, itemValueKey and itemDisplayKey are crucial. These keys specify which fields in the map should be used as the value and display text for each dropdown item respectively. These keys support state variable placeholders using the $ symbol, resolved by DataUtil.
• State Variable Placeholders ($): Parameters like value, label, itemValueKey, and itemDisplayKey support state variable placeholders using the $ symbol (e.g., "${STATE_KEY}"). These placeholders are resolved at runtime by the DataUtil.getValue method to fetch values from the application's state.
• Label Behaviors: The labelBehavior parameter allows customization of the label's appearance:
  • "inline": Label appears within the input field when no value is selected and disappears as the user types or selects.
  • "separate": Label is always visible above the input field.
  • "top": Label appears above the input field and stays there.
  • "hide": No label is displayed.
• State Management: MiDropDown is a stateful widget (MiStatefulWidgetOld) and manages its internal state for dropdown items, selected item(s), and loading status. The uniqueId parameter is used for state key generation, ensuring proper state isolation if multiple dropdowns are used.
• Validation: The isRequired parameter enables basic validation to ensure a selection is made.
• API Configuration for Items: The apiForItems parameter expects a JSON map defining an action to fetch data. This map should conform to the MiAction structure, typically including:
  • "actionType": e.g., "apiCall" to indicate an API call.
  • API specific parameters like "apiName", "endpoint", "method", "requestBody", etc., as required by your API action implementation.
  • The API response should be a List, where each element is either a primitive type (String, Number) or a Map (if using itemValueKey and itemDisplayKey).

Example JSON Configurations

Example 1: Simple Single-Select Dropdown with Static Items and State Value

{
  "component": "dropdown",
  "label": "Role",
  "value": "${TEAM_MEMBER.MERCH_ROLE}",
  "items": [
    "Owner",
    "Manager",
    "Delivery Boy"
  ],
  "isRequired": true
}

Explanation of Example 1:

• component: "dropdown": This identifies it as a MiDropDown component.
• label: "Role": Sets the dropdown label.
• value: "${TEAM_MEMBER.MERCH_ROLE}": Sets the initial value by resolving the state variable TEAM_MEMBER.MERCH_ROLE.
• items: ["Owner", "Manager", "Delivery Boy"]: Provides a static list of string items for roles.
• isRequired: true: Makes the dropdown a required field.

Example 2: Dropdown with API Items, Item Keys, and State Value

{
  "component": "dropdown",
  "label": "Merchant",
  "value": "${USER.MERCH_ID}",
  "apiForItems": {
    "actionType": "apiCall",
    "stateKey": "${DATA.ITEMS}",
    "path": "/gl",
    "apiWorkflow": "adminMerch",
    "apiAction": "getAllMerchants",
    "data": {
      "USER_ID": "${global.user.USER_ID}"
    }
  },
  "itemValueKey": "${ID}",
  "itemDisplayKey": "${MERCH_NAME}",
  "isRequired": true
}

Explanation of Example 2:

• component: "dropdown": This identifies it as a MiDropDown component.
• label: "Merchant": Sets the dropdown label.
• value: "${USER.MERCH_ID}": Sets the initial value from state variable USER.MERCH_ID.
• apiForItems: ...: Configures an API call to fetch merchants.
  • actionType: "apiCall": Specifies an API call action.
  • stateKey: "${DATA.ITEMS}": Indicates that the list of items is nested under the key ITEMS in the API response data.
  • API details: "path", "apiWorkflow", "apiAction", "data" define the specific API endpoint and request parameters.
• itemValueKey: "${ID}": Specifies that the item value is extracted using the state variable placeholder ID from each item map in the API response.
• itemDisplayKey: "${MERCH_NAME}": Specifies that the display text is extracted using the state variable placeholder MERCH_NAME from each item map.
• isRequired: true: Makes the dropdown a required field.

Example 3: Multi-Select Dropdown with Search

{
  "component": "dropdown",
  "label": "Select Categories",
  "multiSelect": true,
  "searchable": true,
  "items": ["Electronics", "Clothing", "Books", "Home Appliances", "Sports"],
  "value": ["Electronics", "Books"]
}

Explanation of Example 3:

• component: "dropdown": This is a MiDropDown component.
• label: "Select Categories": Sets the dropdown label.
• multiSelect: true: Enables multi-select mode.
• searchable: true: Enables the search box.
• items: ["Electronics", "Clothing", "Books", "Home Appliances", "Sports"]: Provides a static list of category strings.
• value: ["Electronics", "Books"]: Sets "Electronics" and "Books" as initially selected values in multi-select mode.