multi_select_flutter 2.0.3
multi_select_flutter: ^2.0.3 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.0.3

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
confirmTextTextText("OK")Specifies the confirm button text.
cancelTextTextText("CANCEL")Specifies the cancel button text.
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.
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.
titleString"Select"The title that is displayed at the top of the dialog.
searchPlaceholderString"Search"Set the placeholder text of the search field.
selectedColorColornullSet the color of the checkbox or chip items that are selected.

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
confirmTextTextText("OK")Specifies the confirm button text.
cancelTextTextText("CANCEL")Specifies the cancel button text.
initialChildSizedouble0.3The initial height of the BottomSheet.
initialValueList<dynamic>nullList of selected values. Required to retain values when re-opening the dialog.
itemsList<MultiSelectItem<V>>nullThe source list of options.
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 dialog.
titleString"Select"The title that is displayed at the top of the dialog.
searchPlaceholderString"Search"Set the placeholder text of the search field.
selectedColorColornullSet the color of the checkbox or chip items that are selected.

MultiSelectBottomSheetField #

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

ParameterTypeDefaultUsage
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.
decorationBoxDecorationnullStyle the Container that makes up the chip display.
itemsList<MultiSelectItem>nullThe source list of selected items.
onTapFunction(dynamic)nullFires when a chip is tapped.
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.

252
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