NestedChoiceList #

A powerful Flutter package designed to simplify the selection of items from deeply nested lists. With its robust features, you can create intuitive and flexible user interfaces that enhance the user experience without the constraints of traditional list handling.

Features #

• Create a list widget with a nesting depth ranging from 0 to infinite.
• Support single selection and multiple selection modes.
• Display the navigation path of selections through the nested list.
• Enable search filtering across every page of the nested list.
• Show the selected items at the top of the page.
• Allow selecting all items in multi-selection mode.
• Provide a callback for single selection mode: onTapItem.
• Offer a callback for multi-selection mode: onSelectionChange.
• Include customizable styles via NestedListStyle.

Showcase #

Single selection mode #

default single selection	showNavigationPath=true	enableSearch=true

Multiple selection mode #

default multi selection	enableSelectAll=true	showSelectedItem=true

Installation #

To use NestedChoiceList, you need to add it to your pubspec.yaml file:

dependencies:
  nested_choice_list: latest_version

Then, run flutter pub get to install the package.

Usage #

To use NestedChoiceList in your Flutter app, first import the package:

import 'package:nested_choice_list/nested_choice_list.dart';

Initialize your items using NestedChoiceEntity class #

final items = const [
    NestedChoiceEntity(
      value: 'value1',
      label: 'label1 level1',
      children: [
        NestedChoiceEntity(value: 'value2', label: 'label2 level 2'),
        NestedChoiceEntity(value: 'value3', label: 'label3 level 2'),
        NestedChoiceEntity(
          value: 'value4',
          label: 'label4 level 2',
          children: [
            NestedChoiceEntity(value: 'value2', label: 'label2 level 3'),
            NestedChoiceEntity(value: 'value3', label: 'label3 level 3'),
            NestedChoiceEntity(
              value: 'value4',
              label: 'label4 level 3',
              children: [
                NestedChoiceEntity(value: 'value2', label: 'label2 level 4'),
                NestedChoiceEntity(value: 'value3', label: 'label3 level 4'),
                NestedChoiceEntity(value: 'value4', label: 'label4 level 4'),
              ],
            ),
          ],
        ),
      ],
    ),
    NestedChoiceEntity(
      value: 'value2',
      label: 'label2 level1',
      children: [
        NestedChoiceEntity(value: 'value2', label: 'label2 level 2'),
        NestedChoiceEntity(value: 'value3', label: 'label3 level 2'),
        NestedChoiceEntity(
          value: 'value4',
          label: 'label4 level 2',
          children: [
            NestedChoiceEntity(value: 'value2', label: 'label2 level 3'),
            NestedChoiceEntity(value: 'value3', label: 'label3 level 3'),
            NestedChoiceEntity(value: 'value4', label: 'label4 level 3'),
          ],
        ),
      ],
    ),
    NestedChoiceEntity(
      value: 'value3',
      label: 'label3 level1',
      children: [
        NestedChoiceEntity(value: 'value2', label: 'label2 level 2'),
        NestedChoiceEntity(value: 'value3', label: 'label3 level 2'),
        NestedChoiceEntity(value: 'value4', label: 'label4 level 2'),
      ],
    ),
    NestedChoiceEntity(value: 'value4', label: 'label4 level1'),
  ];

Or Initialize your items using Json map #

final jsonMap = const [
    {
      'value': 'value1',
      'label': 'label1 level1',
      'isDisabled': false,
      'children': [
        {
          'value': 'value2',
          'label': 'label2 level 2',
        },
        {
          'value': 'value3',
          'label': 'label3 level 2',
        },
        {
          'value': 'value4',
          'label': 'label4 level 2',
          'children': [
            {
              'value': 'value2',
              'label': 'label2 level 3',
            },
            {
              'value': 'value3',
              'label': 'label3 level 3',
            },
            {
              'value': 'value4',
              'label': 'label4 level 3',
              'children': [
                {
                  'value': 'value2',
                  'label': 'label2 level 4',
                },
                {
                  'value': 'value3',
                  'label': 'label3 level 4',
                },
                {
                  'value': 'value4',
                  'label': 'label4 level 4',
                }
              ]
            }
          ]
        }
      ]
    },
    {
      'value': 'value2',
      'label': 'label2 level1',
      'children': [
        {
          'value': 'value2',
          'label': 'label2 level 2',
        },
        {
          'value': 'value3',
          'label': 'label3 level 2',
        },
        {
          'value': 'value4',
          'label': 'label4 level 2',
          'children': [
            {
              'value': 'value2',
              'label': 'label2 level 3',
            },
            {
              'value': 'value3',
              'label': 'label3 level 3',
            },
            {
              'value': 'value4',
              'label': 'label4 level 3',
            }
          ]
        }
      ]
    },
    {
      'value': 'value3',
      'label': 'label3 level1',
      'children': [
        {
          'value': 'value2',
          'label': 'label2 level 2',
        },
        {
          'value': 'value3',
          'label': 'label3 level 2',
        },
        {
          'value': 'value4',
          'label': 'label4 level 2',
        }
      ]
    },
    {
      'value': 'value4',
      'label': 'label4 level1',
    }
  ];

final items = jsonMap.map((e) => NestedChoiceEntity.fromJson(e)).toList();

Then pass your items to the widget and use it #

NestedChoiceList(
        items: items,
        showSelectedItems: showSelectedItems,
        enableSelectAll: enableSelectAll,
        showNavigationPath: showNavigationPath,
        enableMultiSelect: enableMultiSelect,
        enableSearch: enableSearch,
        style: const NestedListStyle(),
        // this callback triggers when we are in
        // single select mode (enableMultiSelect = false)
        onTapItem: (item) {
          debugPrint('onTapItem -> $item');
          Navigator.of(context).pop(item);
        },
        // this callback triggers when we are in
        // multi select mode (enableMultiSelect = true)
        onSelectionChange: (items) {
          debugPrint('onSelectionChange -> $items');
          selectedItems = items;
        },
      )

License #

NestedChoiceList is released under the BSD-3-Clause License.