🔍 Precision Select Dropdown

A production-ready, generic, searchable dropdown widget for Flutter.

precision_select_dropdown is built using overlay-based positioning to provide precise UI behavior, debounced search, outside tap dismissal, and full customization support.

Designed for scalability, clean architecture, and enterprise-grade applications.

✨ Features

  • ✅ Generic <T> type support
  • ✅ Search field inside dropdown
  • ✅ Overlay-based dropdown positioning
  • ✅ Outside tap dismissal (like native dropdown)
  • ✅ Android back button handling
  • ✅ Debounced search
  • ✅ Custom item builder
  • ✅ Custom search matcher
  • ✅ Empty state (“No Data Found”)
  • ✅ Dart 3 & Null Safety support
  • ✅ Clean lifecycle management

📸 Preview

Collapsed State

Collapsed

Expanded with Options

Expanded

Search in Action

Search

No Data Found State

No Data

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  precision_select_dropdown: ^0.0.1

Then run:

flutter pub get

🛠 Basic Usage

PrecisionSelectDropdown<String>(
  items: const [
    'Apple',
    'Banana',
    'Orange',
    'Mango',
    'Pineapple',
  ],
  itemLabelBuilder: (item) => item,
  hintText: 'Select a fruit',
  onChanged: (value) {
    debugPrint("Selected: $value");
  },
)

🧠 Advanced Usage (Custom Search + Custom UI)

PrecisionSelectDropdown<User>(
  items: users,
  hintText: "Select User",
  itemLabelBuilder: (user) => user.name,
  searchMatcher: (user, query) =>
      user.name.toLowerCase().contains(query.toLowerCase()) ||
      user.email.toLowerCase().contains(query.toLowerCase()),
  itemBuilder: (context, user) => ListTile(
    title: Text(user.name),
    subtitle: Text(user.email),
  ),
  onChanged: (value) {},
),

⚙️ Parameters

Parameter Type Description
items List<T> Data source
itemLabelBuilder String Function(T) Converts item to display text
itemBuilder Widget Function(BuildContext, T)? Custom item UI
searchMatcher bool Function(T, String)? Custom search logic
onChanged ValueChanged<T?> Selection callback
initialValue T? Preselected value
hintText String Placeholder text
enabled bool Enable/disable dropdown
maxHeight double Maximum dropdown height

🏗 Architecture

This widget is implemented using:

  • OverlayEntry
  • CompositedTransformFollower
  • LayerLink
  • Debounced filtering
  • Full lifecycle safety
  • Outside tap barrier handling
  • Android back button support

The architecture keeps business logic (search filtering) decoupled from UI rendering, making it extensible and testable.

🧪 Example

A full working example is available inside the /example folder.

To run it:

cd example
flutter run

📌 Upcoming Features

  • 🔲 Multi-select support
  • 🔲 Async API search support
  • 🔲 FormField integration with validation
  • 🔲 Clear/reset icon
  • 🔲 Animated open/close transitions
  • 🔲 Dialog mode (fullscreen search)
  • 🔲 Controller-based architecture
  • 🔲 Keyboard navigation support
  • 🔲 Accessibility improvements
  • 🔲 Advanced theming customization

🤝 Contributing

Contributions are welcome.

If you’d like to improve this package:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

For major changes, please open an issue first to discuss the proposal.

Development Setup

  1. Clone the repository
  2. Run dart pub get
  3. Make your changes
  4. Run dart test to ensure tests pass
  5. Run dart analyze to check for issues
  6. Submit a pull request

License

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

🙋‍♂️ Support

If you find this package useful, please consider giving it a ⭐ on GitHub.

Example

See the example/ directory for a complete usage example.

Changelog

See CHANGELOG.md for a detailed list of changes.

Made with ❤️ for the Dart community

Libraries

precision_select_dropdown