multi_select_flutter 2.3.0
multi_select_flutter: ^2.3.0 copied to clipboard

A flexible multi select package for Flutter. Make multi select widgets the way you want.

Multi Select Flutter #

Pub Version

Multi Select Flutter is a package for easily creating multi-select widgets in a variety of ways.

drawing           drawing

Features #

  • Supports FormField features like validator.
  • Neutral default design that can be altered to your heart's content.
  • Choose between a Dialog or BottomSheet style widget.
  • Easily switch the listType from LIST to CHIP.
  • Make your multi select searchable for larger lists.

Install #

Add this to your pubspec.yaml file:

dependencies:
  multi_select_flutter: ^2.3.0

Usage #

MultiSelectDialog #

Can be used in the builder of showDialog() and triggered with your own button.

void _showMultiSelectDialog(BuildContext context) async {
  await showDialog(
    context: context,
    builder: (ctx) {
      return  MultiSelectDialog(
        items: _animals.map((e) => MultiSelectItem(e, e)).toList(),
        initialValue: _selectedAnimals,
        onConfirm: (values) {...},
      );
    },
  );
}

MultiSelectBottomSheet #

Can be used in the builder of showModalBottomSheet() and triggered with your own button.

void _showMultiSelect(BuildContext context) async {
  await showModalBottomSheet(
    isScrollControlled: true, // required for min/max child size
    context: context,
    builder: (ctx) {
      return  MultiSelectBottomSheet(
        items: _animals.map((e) => MultiSelectItem(e, e)).toList(),
        initialValue: _selectedAnimals,
        onConfirm: (values) {...},
        maxChildSize: 0.8,
      );
    },
  );
}

MultiSelectChipDisplay #

This widget can be used alongside your own button, or it can be specified as a chipDisplay parameter of widgets like MultiSelectDialogField.

To use this widget effectively, make sure to set the state any time the source list is changed.

You can also remove items from the source list in the onTap function.

MultiSelectChipDisplay(
  items: _selectedAnimals.map((e) => MultiSelectItem(e, e)).toList(),
  onTap: (value) {
    setState(() {
      _selectedAnimals.remove(value);
    });
  },
),

When using the chipDisplay parameter as part of a MultiSelectDialogField for example, the MultiSelectChipDisplay still renders outside the BoxDecoration of the field as seen here:

chipDisplay

If you want to encapsulate the MultiSelectChipDisplay, wrap the MultiSelectDialogField in a Container and apply the decoration to that instead:

Container(
  decoration: BoxDecoration(...),
  child: MultiSelectDialogField(
    items: _items,
    chipDisplay: MultiSelectChipDisplay(...),
  ),
),
chipDisplay

MultiSelectDialogField / MultiSelectBottomSheetField #

These widgets provide an InkWell button which open the dialog or bottom sheet.

MultiSelectBottomSheetField(
  items: _animals.map((e) => MultiSelectItem(e, e.name)).toList(),
  listType: MultiSelectListType.CHIP,
  searchable: true,
  decoration: BoxDecoration(...),
  onConfirm: (values) {
    setState(() {
      _selectedAnimals = values;
    });
  },
  chipDisplay: MultiSelectChipDisplay(...),
),

MultiSelectDialogFormField / MultiSelectBottomSheetFormField #

These widgets are the FormField versions of MultiSelectDialogField and MultiSelectBottomSheetField. You can make use of FormField parameters such as validator and onSaved.

It comes with a default bottom-border that can be overriden with the decoration parameter.

MultiSelectDialogFormField(
	items: _animals.map((e) => MultiSelectItem(e, e.name)).toList(),
	key: _multiSelectKey,
	validator: (value) {
	  if (value == null || value.isEmpty) {
	    return  "Required";
	  }
	  return  null;
	},
	onConfirm: (values) {
	  setState(() {
	    _selectedAnimals = values;
	  });
	  _multiSelectKey.currentState.validate();
	},
),

Constructors #

MultiSelectDialog #

ParameterTypeDefaultDescription
backgroundColorColornullSet the background color of the dialog.
cancelTextTextText("CANCEL")Specifies the cancel button text.
confirmTextTextText("OK")Specifies the confirm button text.
chipColorColorprimaryColorSet the chip color when using a CHIP style list.
closeSearchIconIconIcon(Icons.close)The icon button that hides the search field .
coloratorColor Function(V)nullSet the selected color of individual items based on their value. Applies to both chips and checkboxes.
heightdoublenullGive the dialog a fixed height.
initialValueList<dynamic>nullList of selected values. Required to retain values when re-opening the dialog.
itemsList<MultiSelectItem<V>>nullThe source list of options.
itemsTextStyleTextStylenullSpecifies the style of text on chips or list tiles.
listTypeMultiSelectListTypeMultiSelectListType.LISTChange the listType. Can be either  MultiSelectListType.LIST or MultiSelectListType.CHIP
onSelectionChangedFunction(List<dynamic>)nullFires when an item is selected or unselected.
onConfirmFunction(ListnullFires when the confirm button is pressed.
searchableboolfalseToggle search functionality within the dialog.
searchHintStyleTextStylenullStyle the text of the search hint.
searchIconIconIcon(Icons.search)The icon button that shows the search field.
searchPlaceholderString"Search"Set the placeholder text of the search field.
searchTextStyleTextStylenullStyle the search text.
selectedColorColornullSet the color of the checkbox or chip items that are selected.
titleString"Select"The title that is displayed at the top of the dialog.

MultiSelectDialogField #

MultiSelectDialogField has all the parameters of MultiSelectDialog plus these extra parameters:

ParameterTypeDefaultDescription
barrierColorColornullSet the color of the space outside the dialog.
buttonTextText"Select"Set text that is displayed on the button.
buttonIconIconIcons.arrow_downwardSpecify the button icon.
chipDisplayMultiSelectChipDisplaynullAttach a MultiSelectChipDisplay to this field.
decorationBoxDecorationnullStyle the Container that makes up the field.

MultiSelectBottomSheet #

ParameterTypeDefaultDescription
cancelTextTextText("CANCEL")Specifies the cancel button text.
confirmTextTextText("OK")Specifies the confirm button text.
chipColorColorprimaryColorSet the chip color when using a CHIP style list.
closeSearchIconIconIcon(Icons.close)The icon button that hides the search field .
coloratorColor Function(V)nullSet the selected color of individual items based on their value. Applies to both chips and checkboxes.
initialChildSizedouble0.3The initial height of the BottomSheet.
initialValueList<dynamic>nullList of selected values. Required to retain values when re-opening the BottomSheet.
itemsList<MultiSelectItem<V>>nullThe source list of options.
itemsTextStyleTextStylenullSpecifies the style of text on chips or list tiles.
listTypeMultiSelectListTypeMultiSelectListType.LISTChange the listType. Can be either  MultiSelectListType.LIST or MultiSelectListType.CHIP
maxChildSizedouble0.6Set the maximum height threshold of the BottomSheet.
minChildSizedouble0.3Set the minimum height threshold of the BottomSheet before it closes.
onSelectionChangedFunction(List<dynamic>)nullFires when an item is selected or unselected.
onConfirmFunction(ListnullFires when the confirm button is pressed.
searchableboolfalseToggle search functionality within the BottomSheet.
searchHintStyleTextStylenullStyle the text of the search hint.
searchIconIconIcon(Icons.search)The icon button that shows the search field.
searchPlaceholderString"Search"Set the placeholder text of the search field.
searchTextStyleTextStylenullStyle the search text.
selectedColorColornullSet the color of the checkbox or chip items that are selected.
titleString"Select"The title that is displayed at the top of the BottomSheet.

MultiSelectBottomSheetField #

MultiSelectBottomSheetField has all the parameters of MultiSelectBottomSheet plus these extra parameters:

ParameterTypeDefaultUsage
backgroundColorColornullSet the background color of the BottomSheet.
barrierColorColornullSet the color of the space outside the BottomSheet.
buttonIconIconIcons.arrow_downwardSpecify the button icon.
buttonTextText"Select"Set text that is displayed on the button.
chipDisplayMultiSelectChipDisplaynullAttach a MultiSelectChipDisplay to this field.
decorationBoxDecorationnullStyle the Container that makes up the field.
shapeShapeBorderRoundedRectangleBorder(borderRadius: BorderRadius.vertical(top: Radius.circular(15.0)))Apply a ShapeBorder to alter the edges of the BottomSheet.

MultiSelectDialogFormField / MultiSelectBottomSheetFormField #

These widgets have all the parameters of their non-FormField counterparts, plus these extra parameters which come from the FormField class:

ParameterTypeDefaultDescription
autovalidateList<MultiSelectItem>falseIf true, form fields will validate and update their error text immediately after every change. Default is false.
keyGlobalKey<FormFieldState>nullCan be used to call methods like _multiSelectKey.currentState.validate().
onSavedList<MultiSelectItem>nullA callback that is called whenever we submit the field (usually by calling the save method on a form.
validatorFormFieldValidator<List>nullValidation. See Flutter's documentation.

MultiSelectChipDisplay #

ParameterTypeDefaultDescription
alignmentAlignmentAlignment.centerLeftChange the alignment of the chips.
chipColorColorprimaryColorSet the chip color.
coloratorColor Function(V)nullSet the chip color of individual items based on their value.
decorationBoxDecorationnullStyle the Container that makes up the chip display.
iconIconnullThe icon to display prior to the chip label.
itemsList<MultiSelectItem>nullThe source list of selected items.
onTapFunction(dynamic)nullFires when a chip is tapped.
opacitydoublenullSet the opacity of the chips.
shapeShapeBordernullDefine a shape border for the chips.
textStyleTextStylenullStyle the text on the chips.

Contributing #

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

249
likes
110
pub points
97%
popularity

A flexible multi select package for Flutter. Make multi select widgets the way you want.

Repository (GitHub)
View/report issues

Documentation

Documentation
API reference

License

BSD-2-Clause (LICENSE)

Dependencies

flutter

More

Packages that depend on multi_select_flutter