multi_select_flutter 4.0.0
multi_select_flutter: ^4.0.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 creating multi-select widgets in a variety of ways.


Dialog

BottomSheet

ChoiceChip

Features #

  • Supports FormField features like validator.
  • Neutral default design that can be altered to your heart's content.
  • Choose between Dialog, BottomSheet, or ChoiceChip style widgets.
  • Make your multi select searchable for larger lists.

Install #

Add this to your pubspec.yaml file:

dependencies:
  multi_select_flutter: ^4.0.0

Usage #

MultiSelectDialogField / MultiSelectBottomSheetField #

These widgets provide an InkWell button which open the dialog or bottom sheet and are equipped with FormField features. You can customize it to your liking using the provided parameters.

To store the selected values, you can use the onConfirm parameter. You could also use onSelectionChanged for this.

By default these widgets render a MultiSelectChipDisplay below the field. This can be overridden with the chipDisplay parameter or removed completely by using chipDisplay: MultiSelectChipDisplay.none().

MultiSelectDialogField(
  items: _animals.map((e) => MultiSelectItem(e, e.name)).toList(),
  listType: MultiSelectListType.CHIP,
  onConfirm: (values) {
    _selectedAnimals = values;
  },
),

MultiSelectDialog / MultiSelectBottomSheet #

           

If you prefer to create your own button for opening the dialog or bottom sheet, you may do so and then make a call to a function like this:

MultiSelectDialog can be used in the builder of showDialog().

void _showMultiSelect(BuildContext context) async {
  await showDialog(
    context: context,
    builder: (ctx) {
      return  MultiSelectDialog(
        items: _items,
        initialValue: _selectedAnimals,
        onConfirm: (values) {...},
      );
    },
  );
}

MultiSelectBottomSheet can be used in the builder of showModalBottomSheet().

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

MultiSelectChipDisplay #

To display the selected items, this widget can be used alongside your own button or it can be specified as a chipDisplay parameter of widgets like MultiSelectDialogField.

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);
    });
  },
),

A MultiSelectChipDisplay that is part of a MultiSelectDialogField still renders outside the BoxDecoration of the MultiSelectDialogField 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

MultiSelectChipField #

chipField

This widget is similar to MultiSelectChipDisplay, except these chips are the primary interface for selecting items.

MultiSelectChipField<Animal>(
  items: _items,
  icon: Icon(Icons.check),
  onTap: (values) {
    _selectedAnimals = values;
  },
),

Using itemBuilder to create custom items:

MultiSelectChipField<Animal>(
  items: _items,
  key: _multiSelectKey,
  validator: (values) {...}
  itemBuilder: (item, state) {
    // return your custom widget here
    return InkWell(
      onTap: () {
        _selectedAnimals.contains(item.value)
			      ? _selectedAnimals.remove(item.value)
			      : _selectedAnimals.add(item.value);
	      state.didChange(_selectedAnimals);
	      _multiSelectKey.currentState.validate();
	    },
	    child: Text(item.value.name),
    );
  },
),

The itemBuilder param takes a function that will create a widget for each of the provided items.

In order to use validator and other FormField features with custom widgets, you must call state.didChange(_updatedList) any time the list of selected items is updated.

Using scrollControl to auto scroll:

MultiSelectChipField(
  items: _items,
  scrollControl: (controller) {
    _startAnimation(controller);
  },
)

// waits 5 seconds, scrolls to end slow, then back fast
void _startAnimation(ScrollController controller) {
  // when using more than one animation, use async/await
  Future.delayed(const Duration(milliseconds: 5000), () async {
    await controller.animateTo(
      controller.position.maxScrollExtent,
      duration: Duration(milliseconds: 8000), 
      curve: Curves.linear);
      
    await controller.animateTo(
      controller.position.minScrollExtent,
      duration: Duration(milliseconds: 1250),
      curve: Curves.fastLinearToSlowEaseIn);
  });
}

Constructors #

MultiSelectDialog #

ParameterTypeDescription
backgroundColorColorSet the background color of the dialog.
cancelTextTextSpecifies the cancel button text.
checkColorColorSet the color of the check in the checkbox.
closeSearchIconIconIcon(Icons.close)
confirmTextTextSpecifies the confirm button text.
coloratorColorFunction(V) Set the selected color of individual items based on their value. Applies to both chips and checkboxes.
heightdoubleGive the dialog a fixed height.
initialValueList<V>List of selected values. Required to retain values when re-opening the dialog.
itemsList<MultiSelectItem<V>>The source list of options.
itemsTextStyleTextStyleSpecifies the style of text on chips or list tiles.
listTypeMultiSelectListTypeChange the listType. Can be either  MultiSelectListType.LIST or MultiSelectListType.CHIP
onSelectionChangedFunction(List<V>)Fires when an item is selected or unselected.
onConfirmFunction(ListFires when the confirm button is pressed.
searchableboolEnables search functionality within the dialog.
searchHintStyleTextStyleStyle the text of the search hint.
searchIconIconThe icon button that shows the search field.
searchHintStringSet the placeholder text of the search field.
searchTextStyleTextStyleStyle the search text.
selectedColorColorSet the color of the checkbox or chip items that are selected.
titleWidgetThe title that is displayed at the top of the dialog.
unselectedColorColorSet the color of the chip body or checkbox border while not selected.

MultiSelectDialogField #

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

ParameterTypeDescription
autovalidateModeAutovalidateModeIf enabled, form fields will validate and update their error text immediately after every change. Default is disabled.
barrierColorColorSet the color of the space outside the dialog.
buttonTextTextSet text that is displayed on the button.
buttonIconIconSpecify the button icon.
chipDisplayMultiSelectChipDisplayOverride the default MultiSelectChipDisplay that belongs to this field.
decorationBoxDecorationStyle the Container that makes up the field.
keyGlobalKey<FormFieldState>Access FormFieldState methods.
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.

MultiSelectBottomSheet #

ParameterTypeDescription
cancelTextTextSpecifies the cancel button text.
checkColorColorSet the color of the check in the checkbox.
confirmTextTextSpecifies the confirm button text.
closeSearchIconIconThe icon button that hides the search field .
coloratorColor Function(V)Set the selected color of individual items based on their value. Applies to both chips and checkboxes.
initialChildSizedoubleThe initial height of the BottomSheet. Default is 0.3
initialValueList<V>List of selected values. Required to retain values when re-opening the BottomSheet.
itemsList<MultiSelectItem<V>>The source list of options.
itemsTextStyleTextStyleSpecifies the style of text on chips or list tiles.
listTypeMultiSelectListTypeMultiSelectListType.LIST
maxChildSizedoubleSet the maximum height threshold of the BottomSheet. Default is 0.6
minChildSizedoubleSet the minimum height threshold of the BottomSheet before it closes. Default is 0.3
onSelectionChangedFunction(List<V>)Fires when an item is selected or unselected.
onConfirmFunction(ListFires when the confirm button is pressed.
searchableboolToggle search functionality within the BottomSheet.
searchHintStringSet the placeholder text of the search field.
searchHintStyleTextStyleStyle the text of the search hint.
searchIconIconThe icon button that shows the search field.
searchTextStyleTextStyleStyle the search text.
selectedColorColorSet the color of the checkbox or chip items that are selected.
titleWidgetThe title that is displayed at the top of the BottomSheet.
unselectedColorColorSet the color of the chip body or checkbox border while not selected.

MultiSelectBottomSheetField #

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

ParameterTypeDescription
autovalidateModeAutovalidateModeIf enabled, form fields will validate and update their error text immediately after every change. Default is disabled.
backgroundColorColorSet the background color of the BottomSheet.
barrierColorColorSet the color of the space outside the BottomSheet.
buttonIconIconSpecify the button icon.
buttonTextTextSet text that is displayed on the button.
chipDisplayMultiSelectChipDisplayOverride the default MultiSelectChipDisplay that belongs to this field.
decorationBoxDecorationStyle the Container that makes up the field.
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.
shapeShapeBorderApply a ShapeBorder to alter the edges of the BottomSheet. Default is a RoundedRectangleBorder with top circular radius of 15.
validatorFormFieldValidator<List>Validation. See Flutter's documentation.

MultiSelectChipField #

ParameterTypeDescription
autovalidateModeAutovalidateModeIf enabled, form fields will validate and update their error text immediately after every change. Default is disabled.
chipColorColorSet the chip color.
chipShapeShapeBordeDefine a ShapeBorder for the chips.
closeSearchIconIconThe icon button that hides the search field .
coloratorColor Function(V)Set the selected chip color of individual items based on their value.
decorationBoxDecorationStyle the surrounding Container.
headerColorColorSet the header color.
heightdoubleSet the height of the selectable area.
iconIconThe icon to display prior to the chip label.
initialValueList<V>List of selected values before any interaction.
itemBuilderFunction(MultiSelectItem<V>, FormFieldState<List<V>>)Build a custom widget that gets created dynamically for each item.
itemsList<MultiSelectItem<V>>The source list of options.
keyGlobalKey<FormFieldState>Can be used to call methods like _multiSelectKey.currentState.validate().
onSavedList<MultiSelectItem>A callback that is called whenever the field is submitted (usually by calling the save method on a form.
onTapFunction(V)Fires when a chip is tapped.
scrollboolEnables horizontal scrolling.
scrollBarHorizontalScrollBarDefine a scroll bar.
scrollControlFunction(ScrollController)Make use of the ScrollController to automatically scroll through the list.
searchableboolToggle search functionality.
searchHintStringSet the placeholder text of the search field.
searchHintStyleTextStyleStyle the text of the search hint.
searchIconIconThe icon button that shows the search field.
searchTextStyleTextStyleStyle the search text.
selectedChipColorColorSet the color of the chip items that are selected.
selectedTextStyleTextStyleSet the TextStyle on selected chips.
showHeaderboolDetermines whether to show the header.
textStyleTextStyleStyle the text on the chips.
titleWidgetThe title that is displayed in the header.
validatorFormFieldValidator<List>Validation. See Flutter's documentation.

MultiSelectChipDisplay #

ParameterTypeDescription
alignmentAlignmentChange the alignment of the chips. Default is Alignment.centerLeft.
chipColorColorSet the chip color.
coloratorColor Function(V)Set the chip color of individual items based on their value.
decorationBoxDecorationStyle the Container that makes up the chip display.
heightdoubleSet a fixed height.
iconIconThe icon to display prior to the chip label.
itemsList<MultiSelectItem>The source list of selected items.
onTapFunction(V)Fires when a chip is tapped.
scrollboolEnables horizontal scroll instead of wrap.
scrollBarHorizontalScrollBarEnable the scroll bar.
shapeShapeBorderDefine a ShapeBorder for the chips.
textStyleTextStyleStyle 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
120
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

collection, flutter

More

Packages that depend on multi_select_flutter