Alphabet Navigation

License GitHub Contributors Stars GitHub Closed Issues

alphabet_navigation is a Flutter package that provides a dynamic, scrollable list view with an alphabetical index. It’s perfect for apps that need a quick and intuitive way to navigate long lists by alphabet.

Features

  • x A vertical alphabetical navigation bar for quick access to sections.
  • x Smooth scrolling to the desired section when an alphabet is selected.
  • x Fully customizable list items and navigation styles.
  • x Built-in search bar for filtering items dynamically.
  • x Search field is optional & can be customized.
  • x Dynamic list height is optional & can be customized.
  • x Alphabetic list direction is configurable.
  • x Allow users to easily configure colors, fonts, and styles.
  • x Lightweight and easy to integrate into any Flutter project.
  • x Compatible with all platforms.
  • x Clear documentation.

Demo

Demo GIF

Installation

To use the alphabet_navigation package, follow these steps:

Run this on your project terminal:

flutter pub add alphabet_navigation

or manually configure pubspec.yml file

  1. Add the package to your pubspec.yaml file:

    dependencies:
  alphabet_navigation: ^2.1.0 // replace with latest version

  2. Run the following command to get the package:

    flutter pub get

Usage

Here’s how you can use the AlphabetNavigation widget in your app:

Example 1:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  dynamicListHeight: 80, // Dynamic list height (optional)
  showSearchField: true, // Toggle for search field (optional)
  circleSelectedLetter: true, // Is circle apply for the selected letter (optional)
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 2:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  searchFieldHintText: "Search here...", // Search field hint text
  searchFieldTextStyle: TextStyle(
   color: Colors.blue.shade800,
   fontWeight: FontWeight.w500,
   fontSize: 16,
  ),
  searchFieldHintTextStyle: TextStyle(
    color: Colors.grey.shade300,
    fontWeight: FontWeight.w500,
    fontSize: 16,
  ),
  searchFieldIcon: Icon(Icons.search, color: Colors.blue.shade800,), // Search field icon
  searchFieldEndIconColor: Colors.blue.shade800, // Search field clear icon color
  listDirection: ListDirection.left, // Direction of the list. If [ListDirection.left], the list will be from right to left (optional)
  showSearchField: true, // Toggle for search field (optional)
  circleSelectedLetter: true, // Is circle apply for the selected letter (optional)
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 3:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  showSearchField: true, // Toggle for search field (optional)
  alphabetListBackgroundColor: Colors.tealAccent, // Alphabet list background color
  selectedColor: Colors.white70, // Selected color for the alphabet
  unselectedColor: Colors.black38, // Unselected color for the alphabet
  circleSelectedLetter: true, // Is circle apply for the selected letter (optional)
  circleSelectedBackgroundColor: Colors.blue, // Selected circle background color
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 4:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  showSearchField: false, // Toggle for search field (optional)
  circleSelectedLetter: false, // Is circle apply for the selected letter (optional)
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 4:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  circleSelectedLetter: false, // Is circle apply for the selected letter (optional)
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 5:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  circleSelectedLetter: false, // Is circle apply for the selected letter (optional)
  alphabetListBackgroundColor: Colors.transparent, // Alphabet list background color
  selectedColor: Colors.blue, // Selected color for the alphabet
  unselectedColor: Colors.grey.shade600, // Unselected color for the alphabet
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)

Example 6:

AlphabetNavigation(
  stringList: stringList, // Pass the string list for alphabet mapping
  dynamicList: dynamicList, // Pass the dynamic list for content
  showSearchField: true, // Toggle for search field (optional)
  circleSelectedLetter: true, // Is circle apply for the selected letter (optional)
  circleBorderRadius: 50.0, // Border radius for the selected letter circle and alphabet list border
  scrollAnimationCurve: Curves.easeInCubic, // Scroll animation curve
  itemBuilder: (context, index, searchFilterList) {}, // Item builder
)
Example 1 Example 2 Example 3
Example 4 Example 5 Example 6

Parameters

Parameter Type Description
stringList List<String> List of strings for alphabetical grouping.
dynamicList List<dynamic> Data list to be displayed.
dynamicListHeight double Dynamic list height.
listDirection ListDirection Direction of the list.
showSearchField bool Toggle for search field.
searchFieldTextStyle TextStyle Search field text style.
searchFieldHintText String Search field hint text.
searchFieldHintTextStyle TextStyle Search field hint style.
searchFieldIcon Icon Search field icon.
searchFieldBackgroundColor Color Search field background color.
searchFieldEndIconColor Color Search field icon color.
alphabetListBackgroundColor Color Alphabet list background color.
selectedColor Color Selected alphabet color
unselectedColor Color Unselected alphabet color
circleSelectedLetter bool Is circle apply for the selected letter.
circleSelectedBackgroundColor Color Circle background color for the selected letter.
circleBorderRadius double Border radius for the selected letter circle
scrollAnimationCurve Curve Scroll animation curve.
itemBuilder Function(BuildContext, int, dynamic) Function to build list items dynamically.

Future Plans

Here are some planned features for future releases:

  • Accessibility Improvements: Enhanced support for voice-over and screen readers.
  • Horizontal Navigation: Add support for horizontal alphabetical navigation.
  • Custom Alphabet Set: Support for custom navigation sets like 'A', 'B', 'C', '1', '2', '3'.
  • Multi-Language Support: Enable alphabetical navigation for other languages.

Contributing

We welcome contributions from the community! If you encounter any issues or have feature suggestions, feel free to open an issue or submit a pull request on our GitHub repository.

Additional information

License

This project is licensed under the MIT License - see the LICENSE file for details.

CONTRIBUTORS

Contributors
Akash Das

Happy Coding 👨‍💻

Libraries

alphabet_navigation