dropinity #

A powerful and highly customizable Flutter dropdown widget with built-in search functionality and pagination support. Dropinity makes it easy to handle both local and remote data sources with a beautiful, animated interface.

Features #

• 🔍 Intelligent Search: Real-time filtering with custom search logic
• 📡 API Integration: Seamless pagination support through Pagify package
• 💾 Dual Mode: Works with both static lists and dynamic API data
• 🎨 Fully Customizable: Complete control over UI, styling, and behavior
• 🎭 Smooth Animations: Beautiful expand/collapse transitions
• 🎯 Type Safe: Full generic type support for your models

Dependencies #

Dropinity depends on the Pagify package for pagination functionality.

Installation #

Add to your pubspec.yaml:

dependencies:
  dropinity: ^0.0.1

Then run:

flutter pub get

Usage #

Dropinity has two modes of operation:

1. Local Mode (Static Data) #

Perfect for predefined lists or data that doesn't require API calls.

typedef DropinityLocal<Model> = Dropinity<void, Model>;

DropinityLocal<Model>(
  dropdownTitle: Text(
    'Select Country',
    style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
  ),
  listHeight: 300,
  buttonData: ButtonData(
    buttonWidth: double.infinity,
    buttonHeight: 55,
    hint: Text('Choose a country...'),
    selectedItemWidget: (country) => Text(
      country ?? '',
      style: TextStyle(fontSize: 16),
    ),
    buttonBorderRadius: BorderRadius.circular(12),
    buttonBorderColor: Colors.blue,
  ),
  textFieldData: TextFieldData(
    controller: TextEditingController(),
    title: 'Search',
    prefixIcon: Icon(Icons.search),
    borderRadius: 8,
    onSearch: (pattern, country) {
      if (pattern == null || country == null) return false;
      return country.toLowerCase().contains(pattern.toLowerCase());
    },
  ),
  values: [
    'United States',
    'Canada',
    'Mexico',
    'Brazil',
    'Argentina',
    'United Kingdom',
    'Germany',
    'France',
  ],
  valuesData: ValuesData(
    itemBuilder: (context, index, country) {
      return Container(
        padding: EdgeInsets.symmetric(vertical: 12, horizontal: 16),
        child: Text(country, style: TextStyle(fontSize: 15)),
      );
    },
  ),
  onChanged: (selectedCountry) {
    print('Selected: $selectedCountry');
  },
)

2. API Mode (Paginated Remote Data) #

Ideal for large datasets with server-side pagination and filtering.

// Create a controller
final controller = PagifyController<User>();

Dropify<ApiResponse, User>.withApiRequest(
  dropdownTitle: Text(
    'Select User',
    style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
  ),
  listHeight: 400,
  buttonData: ButtonData(
    buttonWidth: double.infinity,
    buttonHeight: 55,
    hint: Row(
      children: [
        Icon(Icons.person_outline, color: Colors.grey),
        SizedBox(width: 8),
        Text('Search users...'),
      ],
    ),
    selectedItemWidget: (user) => Row(
      children: [
        CircleAvatar(
          radius: 16,
          backgroundImage: NetworkImage(user?.avatarUrl ?? ''),
        ),
        SizedBox(width: 12),
        Text(user?.name ?? ''),
      ],
    ),
    expandedListIcon: Icon(Icons.keyboard_arrow_up, color: Colors.blue),
    collapsedListIcon: Icon(Icons.keyboard_arrow_down, color: Colors.grey),
  ),
  textFieldData: TextFieldData(
    controller: TextEditingController(),
    title: 'Search by name or email',
    prefixIcon: Icon(Icons.search),
    borderRadius: 10,
    fillColor: Colors.grey[100],
    onSearch: (pattern, user) {
      if (pattern == null || user == null) return false;
      return user.name.toLowerCase().contains(pattern.toLowerCase()) ||
             user.email.toLowerCase().contains(pattern.toLowerCase());
    },
  ),
  pagifyData: SearchableDropdownPagifyData(
    controller: controller,
    asyncCall: (context, page) async {
      // Your API call
      final response = await ApiService.getUsers(page: page);
      return response;
    },
    mapper: (response) {
      return PagifyData(
        data: response.users,
        total: response.total,
        totalPages: response.totalPages,
      );
    },
    errorMapper: (response) => response.error,
    itemBuilder: (context, data, index, user) {
      return Container(
        padding: EdgeInsets.symmetric(vertical: 10, horizontal: 16),
        child: Row(
          children: [
            CircleAvatar(
              radius: 20,
              backgroundImage: NetworkImage(user.avatarUrl),
            ),
            SizedBox(width: 12),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    user.name,
                    style: TextStyle(
                      fontSize: 15,
                      fontWeight: FontWeight.w500,
                    ),
                  ),
                  Text(
                    user.email,
                    style: TextStyle(
                      fontSize: 13,
                      color: Colors.grey[600],
                    ),
                  ),
                ],
              ),
            ),
          ],
        ),
      );
    },
    loadingBuilder: Center(
      child: CircularProgressIndicator(),
    ),
    errorBuilder: (error) => Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Icon(Icons.error_outline, size: 48, color: Colors.red),
          SizedBox(height: 16),
          Text('Error: ${error.message}'),
        ],
      ),
    ),
    emptyListView: Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Icon(Icons.inbox_outlined, size: 64, color: Colors.grey),
          SizedBox(height: 16),
          Text('No users found'),
        ],
      ),
    ),
    noConnectionText: 'No internet connection',
    padding: EdgeInsets.all(8),
  ),
  onChanged: (selectedUser) {
    print('Selected: ${selectedUser.name}');
  },
)

API Reference #

Constructors #

Dropify() - Local Mode

const Dropify({
  Key? key,
  Widget? dropdownTitle,
  double? listHeight,
  required ButtonData<Model> buttonData,
  required TextFieldData<Model> textFieldData,
  required List<Model> values,
  required ValuesData<Model> valuesData,
  required FutureOr<void> Function(Model val) onChanged,
})

Dropify.withApiRequest() - API Mode

const Dropify.withApiRequest({
  Key? key,
  Widget? dropdownTitle,
  double? listHeight,
  required ButtonData<Model> buttonData,
  required TextFieldData<Model> textFieldData,
  required SearchableDropdownPagifyData<FullResponse, Model> pagifyData,
  required FutureOr<void> Function(Model val) onChanged,
})

Configuration Classes #

ButtonData

Defines the appearance and behavior of the dropdown button.

ButtonData<Model>({
  required Widget Function(Model? selectedElement) selectedItemWidget,
  Color? buttonBorderColor,
  BorderRadius? buttonBorderRadius,
  Widget? hint,
  Color? color,
  EdgeInsetsGeometry? padding,
  double buttonWidth = double.infinity,
  double buttonHeight = 50,
  Widget? expandedListIcon,
  Widget? collapsedListIcon,
})

Properties:

• selectedItemWidget: Builder for displaying the selected item
• hint: Widget shown when no item is selected
• buttonWidth: Width of the button (default: double.infinity)
• buttonHeight: Height of the button (default: 50)
• buttonBorderRadius: Border radius of the button
• buttonBorderColor: Color of the button border
• color: Background color of the button
• padding: Internal padding of the button
• expandedListIcon: Icon shown when dropdown is open
• collapsedListIcon: Icon shown when dropdown is closed

TextFieldData

Configures the search field inside the dropdown.

TextFieldData<Model>({
  required bool Function(String? pattern, Model? element) onSearch,
  TextEditingController? controller,
  String? title,
  Widget? prefixIcon,
  Widget? suffixIcon,
  double? borderRadius,
  Color? borderColor,
  EdgeInsetsGeometry? contentPadding,
  Color? fillColor,
  int? maxLength,
  TextStyle? style,
})

Properties:

• onSearch: Function that defines search logic (returns true if item matches)
• controller: Text editing controller for the search field
• title: Label/hint text for the search field
• prefixIcon: Icon at the start of the search field
• suffixIcon: Icon at the end of the search field
• borderRadius: Border radius of the search field
• borderColor: Color of the search field border
• contentPadding: Internal padding of the search field
• fillColor: Background color of the search field
• maxLength: Maximum character length
• style: Text style for the search field

ValuesData (Local Mode Only)

Defines how items are displayed in local mode.

ValuesData<Model>({
  required Widget Function(BuildContext context, int i, Model element) itemBuilder,
})

Properties:

• itemBuilder: Builder function for each list item

SearchableDropdownPagifyData (API Mode Only)

Configures pagination and API integration.

SearchableDropdownPagifyData<FullResponse, Model>({
  required Future<FullResponse> Function(BuildContext context, int page) asyncCall,
  required PagifyData<Model> Function(FullResponse response) mapper,
  required PagifyErrorMapper errorMapper,
  required Widget Function(BuildContext context, List<Model> data, int index, Model element) itemBuilder,
  required PagifyController<Model> controller,
  EdgeInsetsGeometry padding = const EdgeInsets.all(0),
  double? itemExtent,
  FutureOr<void> Function(PagifyAsyncCallStatus)? onUpdateStatus,
  FutureOr<void> Function()? onLoading,
  FutureOr<void> Function(BuildContext, List<dynamic>)? onSuccess,
  FutureOr<void> Function(BuildContext, int, PagifyException)? onError,
  bool ignoreErrorBuilderWhenErrorOccursAndListIsNotEmpty = true,
  bool showNoDataAlert = false,
  Widget? loadingBuilder,
  Widget Function(PagifyException)? errorBuilder,
  Widget? emptyListView,
  String? noConnectionText,
})

Properties:

• controller: Pagify controller instance
• asyncCall: Function to fetch paginated data
• mapper: Maps API response to PagifyData
• errorMapper: Maps errors from the response
• itemBuilder: Builder for each list item
• loadingBuilder: Widget shown while loading
• errorBuilder: Widget shown on error
• emptyListView: Widget shown when list is empty
• padding: Padding around the list
• itemExtent: Fixed height for list items
• noConnectionText: Message for no internet connection
• onUpdateStatus: Callback for status changes
• onLoading: Callback when loading starts
• onSuccess: Callback on successful load
• onError: Callback on error

Advanced Examples #

Custom Styling Example #

Dropify<dynamic, Product>(
  dropdownTitle: Container(
    padding: EdgeInsets.symmetric(vertical: 8),
    child: Text(
      'Select Product',
      style: TextStyle(
        fontSize: 18,
        fontWeight: FontWeight.bold,
        color: Colors.blue[900],
      ),
    ),
  ),
  listHeight: 350,
  buttonData: ButtonData(
    buttonWidth: double.infinity,
    buttonHeight: 60,
    color: Colors.blue[50],
    buttonBorderRadius: BorderRadius.circular(16),
    buttonBorderColor: Colors.blue[300],
    padding: EdgeInsets.symmetric(horizontal: 20, vertical: 12),
    hint: Row(
      children: [
        Icon(Icons.shopping_cart_outlined, color: Colors.blue),
        SizedBox(width: 12),
        Text(
          'Choose a product...',
          style: TextStyle(color: Colors.grey[600]),
        ),
      ],
    ),
    selectedItemWidget: (product) => Row(
      children: [
        Container(
          padding: EdgeInsets.all(8),
          decoration: BoxDecoration(
            color: Colors.blue,
            borderRadius: BorderRadius.circular(8),
          ),
          child: Icon(Icons.check, color: Colors.white, size: 16),
        ),
        SizedBox(width: 12),
        Expanded(
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(
                product?.name ?? '',
                style: TextStyle(fontWeight: FontWeight.bold),
              ),
              Text(
                '\$${product?.price.toStringAsFixed(2)}',
                style: TextStyle(color: Colors.green, fontSize: 12),
              ),
            ],
          ),
        ),
      ],
    ),
    expandedListIcon: Icon(Icons.expand_less, color: Colors.blue, size: 28),
    collapsedListIcon: Icon(Icons.expand_more, color: Colors.blue, size: 28),
  ),
  textFieldData: TextFieldData(
    controller: TextEditingController(),
    title: 'Search products by name or SKU',
    prefixIcon: Icon(Icons.search, color: Colors.blue),
    suffixIcon: Icon(Icons.filter_list, color: Colors.grey),
    borderRadius: 12,
    borderColor: Colors.blue[200],
    fillColor: Colors.white,
    contentPadding: EdgeInsets.all(16),
    onSearch: (pattern, product) {
      if (pattern == null || product == null) return false;
      return product.name.toLowerCase().contains(pattern.toLowerCase()) ||
             product.sku.toLowerCase().contains(pattern.toLowerCase());
    },
  ),
  values: products, // Your product list
  valuesData: ValuesData(
    itemBuilder: (context, index, product) {
      return Container(
        margin: EdgeInsets.only(bottom: 8),
        padding: EdgeInsets.all(12),
        decoration: BoxDecoration(
          color: Colors.white,
          borderRadius: BorderRadius.circular(10),
          border: Border.all(color: Colors.grey[200]!),
        ),
        child: Row(
          children: [
            Container(
              width: 50,
              height: 50,
              decoration: BoxDecoration(
                color: Colors.blue[100],
                borderRadius: BorderRadius.circular(8),
              ),
              child: Icon(Icons.inventory_2, color: Colors.blue),
            ),
            SizedBox(width: 12),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    product.name,
                    style: TextStyle(fontWeight: FontWeight.w600),
                  ),
                  Text(
                    'SKU: ${product.sku}',
                    style: TextStyle(fontSize: 12, color: Colors.grey),
                  ),
                ],
              ),
            ),
            Text(
              '\$${product.price.toStringAsFixed(2)}',
              style: TextStyle(
                fontWeight: FontWeight.bold,
                color: Colors.green,
              ),
            ),
          ],
        ),
      );
    },
  ),
  onChanged: (product) {
    print('Selected: ${product.name}');
  },
)

Form Integration Example #

class MyForm extends StatefulWidget {
  @override
  _MyFormState createState() => _MyFormState();
}

class _MyFormState extends State<MyForm> {
  final _formKey = GlobalKey<FormState>();
  Country? selectedCountry;
  City? selectedCity;
  
  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        children: [
          // Country Dropdown
          Dropify<dynamic, Country>(
            dropdownTitle: Text('Country *'),
            buttonData: ButtonData(
              buttonWidth: double.infinity,
              hint: Text('Select country'),
              selectedItemWidget: (country) => Text(country?.name ?? ''),
            ),
            textFieldData: TextFieldData(
              controller: TextEditingController(),
              onSearch: (pattern, country) =>
                country?.name.toLowerCase().contains(pattern?.toLowerCase() ?? '') ?? false,
            ),
            values: countries,
            valuesData: ValuesData(
              itemBuilder: (context, i, country) => ListTile(
                title: Text(country.name),
              ),
            ),
            onChanged: (country) {
              setState(() {
                selectedCountry = country;
                selectedCity = null; // Reset city when country changes
              });
            },
          ),
          
          SizedBox(height: 16),
          
          // City Dropdown (dependent on country)
          if (selectedCountry != null)
            Dropify<dynamic, City>(
              dropdownTitle: Text('City *'),
              buttonData: ButtonData(
                buttonWidth: double.infinity,
                hint: Text('Select city'),
                selectedItemWidget: (city) => Text(city?.name ?? ''),
              ),
              textFieldData: TextFieldData(
                controller: TextEditingController(),
                onSearch: (pattern, city) =>
                  city?.name.toLowerCase().contains(pattern?.toLowerCase() ?? '') ?? false,
              ),
              values: selectedCountry!.cities,
              valuesData: ValuesData(
                itemBuilder: (context, i, city) => ListTile(
                  title: Text(city.name),
                ),
              ),
              onChanged: (city) {
                setState(() => selectedCity = city);
              },
            ),
          
          SizedBox(height: 24),
          
          ElevatedButton(
            onPressed: () {
              if (selectedCountry != null && selectedCity != null) {
                // Submit form
                print('Country: ${selectedCountry!.name}');
                print('City: ${selectedCity!.name}');
              } else {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Please select all fields')),
                );
              }
            },
            child: Text('Submit'),
          ),
        ],
      ),
    );
  }
}

Performance Considerations #

1. For Large Datasets: Use API mode (Dropify.withApiRequest) with pagination
2. Search Optimization: Implement efficient onSearch logic to avoid performance issues
3. State Management: The widget uses maintainState: true to preserve state when toggling visibility
4. Memory Usage: Local mode keeps all data in memory, so use API mode for very large datasets
5. Controller Disposal: Always dispose controllers in dispose() method

@override
void dispose() {
  textController.dispose();
  pagifyController.dispose();
  super.dispose();
}

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License.

Support #

For issues and feature requests, please file an issue on the GitHub repository.

For questions about the Pagify package, refer to the Pagify documentation.

Made with ❤️ for the Flutter community by Ahmed Emara linkedIn