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

  • Can use MultiSelectFormField for use with validators and other FormField methods.
  • Neutral default design that can be altered to your heart's content.
  • Easily switch the MultiSelectField's dialogType from LIST to CHIP.
  • Make your multi select searchable for large lists.
  • Separate widget for MultiSelectChipDisplay that has the ability to delete from the selected items list when a chip item is tapped.
  • Separate widgets for MultiSelectListDialog / MultiSelectChipDialog that you can simply use in the builder of showDialog(), and can be triggered with your own button.

Install

Add this to your pubspec.yaml file:

dependencies:
  multi_select_flutter: ^1.0.6

Usage

MultiSelectListDialog / MultiSelectChipDialog

These widgets can be used in the builder of showDialog().

  void _showMultiSelectDialog(BuildContext context) async {
    _selectedAnimals = await showDialog(
      context: context,
      builder: (ctx) {
        return MultiSelectListDialog(
          items: _items.map((item) => 
            MultiSelectItem(item, item.name)).toList(),
          initialSelectedItems: _selectedAnimals,
        );
      },
    );
  }

MultiSelectChipDisplay

This widget can be used by itself, alongside one of the dialogs, or it can be specified as a parameter of MultiSelectField / MultiSelectFormField.

To use this widget effectively, make sure to set the state when the list of selected items is changed.

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

List<String> _selectedAnimals = [];

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

Note that when using the chipDisplay parameter as part of a MultiSelectField or MultiSelectFormField, the MultiSelectChipDisplay still renders outside the BoxDecoration of the field as seen here:

chipDisplay

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

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

MultiSelectField

MultiSelectField provides a button which opens the dialog. To save the values from the dialog using this widget, an onConfirm(values) function is provided.

MultiSelectField(
  items: _animals.map((e) => MultiSelectItem(e, e.name)).toList(),
  title: "Animals",
  buttonText: "Favorite Animals"
  dialogType: MultiSelectDialogType.CHIP,
  searchable: true,
  textStyle: TextStyle(fontSize: 20),
  decoration: BoxDecoration(
    color: Theme.of(context).primaryColor.withOpacity(.4),
    border: Border.all(color: Theme.of(context).primaryColor),
  ),
  onConfirm: (results) {
    setState(() {
      _selectedAnimals = results;
    });
  },
  chipDisplay: MultiSelectChipDisplay(
    items: _selectedAnimals.map((e) => MultiSelectItem(e, e)).toList(),
  ),
),

MultiSelectFormField

MultiSelectFormField is the FormField version of MultiSelectField. You can put it into a form and 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.

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

Constructors

MultiSelectListDialog / MultiSelectChipDialog

ParameterTypeUsage
confirmTextStringSpecifies the confirm button text.
cancelTextStringSpecifies the cancel button text.
initialSelectedItemsList<dynamic>List of selected values. Required to retain values when re-opening the dialog.
itemsList<MultiSelectItem>The source list of options to select
onSelectionChangedFunction(List<dynamic>)Fires when an item is selected or unselected.
onConfirmFunction(List<dynamic>)Fires when the confirm button is pressed.
searchableboolToggle search functionality within the dialog.
titleStringThe title that is displayed at the top of the dialog.

MultiSelectChipDisplay

ParameterTypeUsage
alignmentAlignmentChange the alignment of the chips. Default is Alignment.centerLeft
chipColorColorSet the chip color. Default is primary theme color.
decorationBoxDecorationStyle the Container that makes up the chip display.
itemsList<MultiSelectItem>The source list of selected items
onTapFunction(List<dynamic>)Fires when a chip is tapped.
textStyleTextStyleStyle the text on the chips.

MultiSelectField

ParameterTypeUsage
buttonTextStringSet text that is displayed on the button. Default is "Select"
buttonIconIconSpecify the button icon. Default is arrow_downward
confirmTextStringSpecify the text on the confirm button.
cancelTextStringSpecify the text on the cancel button.
dialogTypeMultiSelectDialogTypeStyle the Container that makes up the chip display.
decorationBoxDecorationStyle the Container that makes up the field.
initialValueList<dynamic>Set the initial values before any user interaction has occurred. Useful when MultiSelectField is being re-inserted into the widget tree (such as one inside of a BottomSheet).
itemsList<MultiSelectItem>The source list of selected items
onSelectionChangedFunction(List<dynamic>)Fires when an item is selected or unselected.
onConfirmFunction(List<dynamic>)Fires when confirm is pressed.
searchableboolToggle search functionality within the dialog.
titleStringThe title that is displayed at the top of the dialog. Default is "Select".

MultiSelectFormField

MultiSelectFormField has all the parameters of MultiSelectField plus these extra parameters which come from the FormField class.

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

Contributing

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

Libraries

flutter_multi_select