Paginated TypeAhead #

A TypeAhead (autocomplete) widget for Flutter with built-in infinite scroll pagination, debouncing, and modern declarative overlay management.

License: MIT

[Paginated TypeAhead Demo]

Features #

Infinite Scroll Pagination: Automatically loads more suggestions as the user scrolls to the bottom of the dropdown.
Modern Dart 3 Records: Clean (List<T>? items, bool hasMore) response contract for pagination callbacks.
Declarative Overlay Architecture: Powered by Flutter's OverlayPortal for smooth rendering without manual overlay lifecycle issues.
Deep Customization:
- Custom search text field builder (builder)
- Item builder (itemBuilder) & item separators (separatorBuilder)
- Initial loading (loadingBuilder) & load-more progress (loadMoreLoadingBuilder)
- Empty results (emptyBuilder)
- Error state (errorBuilder) & load-more retry (loadMoreErrorBuilder)
Smart Auto-Flipping: Automatically switches dropdown direction (down / up) when space below is constrained or keyboard appears.
Debounce & Threshold: Configurable debounce duration and minimum characters threshold.
Programmatic Controller: Open, close, toggle, or select items programmatically via SuggestionsController.
Form Support: Seamlessly integrates with Flutter forms (validator, autovalidateMode, inputFormatters).

Getting Started #

Add paginated_typeahead to your pubspec.yaml:

dependencies:
  paginated_typeahead: ^1.1.0

Or install it via terminal:

flutter pub add paginated_typeahead

Import the package:

import 'package:paginated_typeahead/paginated_typeahead.dart';

Usage #

Basic Example #

PaginatedTypeAhead<User>(
  initialPage: 1,
  suggestionsCallback: (query, page) async {
    final response = await apiService.getUsers(query: query, page: page);
    return (response.users, response.hasMorePages);
  },
  itemBuilder: (user) => ListTile(
    title: Text(user.name),
    subtitle: Text(user.email),
  ),
  onSelected: (user) {
    print('Selected user: ${user.name}');
  },
)

Custom Text Field Builder #

Use the builder parameter to supply your own custom TextFormField, input decoration, or custom styling:

PaginatedTypeAhead<User>(
  initialPage: 1,
  builder: (context, controller, focusNode) {
    return TextFormField(
      controller: controller,
      focusNode: focusNode,
      decoration: InputDecoration(
        hintText: 'Search users...',
        prefixIcon: const Icon(Icons.search),
        border: OutlineInputBorder(
          borderRadius: BorderRadius.circular(12),
        ),
      ),
    );
  },
  suggestionsCallback: (query, page) async {
    final response = await apiService.getUsers(query: query, page: page);
    return (response.users, response.hasMorePages);
  },
  itemBuilder: (user) => ListTile(
    title: Text(user.name),
  ),
  onSelected: (user) => print(user.name),
)

Note: Both controller and focusNode provided by the builder must be passed to your text field for overlay positioning and typing events to work properly.

Customizing Status & Pagination Builders #

You can customize each state of the search and pagination lifecycle:

PaginatedTypeAhead<Repository>(
  initialPage: 1,
  suggestionsCallback: (query, page) => repository.search(query, page),
  itemBuilder: (repo) => ListTile(title: Text(repo.name)),
  onSelected: (repo) => selectRepo(repo),
  // Separator between items
  separatorBuilder: (context, index) => const Divider(height: 1),
  // Initial loading indicator
  loadingBuilder: (context) => const Padding(
    padding: EdgeInsets.all(16),
    child: Center(child: CircularProgressIndicator()),
  ),
  // Indicator at the bottom while loading the next page
  loadMoreLoadingBuilder: (context) => const Padding(
    padding: EdgeInsets.all(12),
    child: Center(
      child: SizedBox(
        width: 20,
        height: 20,
        child: CircularProgressIndicator(strokeWidth: 2),
      ),
    ),
  ),
  // Widget displayed when no items match the query
  emptyBuilder: (context) => const Padding(
    padding: EdgeInsets.all(16),
    child: Center(child: Text('No repositories found')),
  ),
  // Widget displayed when initial fetch fails
  errorBuilder: (context, error) => Padding(
    padding: const EdgeInsets.all(16),
    child: Center(
      child: Text(
        'Failed to load: $error',
        style: TextStyle(color: Theme.of(context).colorScheme.error),
      ),
    ),
  ),
  // Retry widget displayed when loading more fails
  loadMoreErrorBuilder: (context, retry) => Padding(
    padding: const EdgeInsets.all(12),
    child: Center(
      child: TextButton.icon(
        onPressed: retry,
        icon: const Icon(Icons.refresh, size: 18),
        label: const Text('Retry loading more'),
      ),
    ),
  ),
)

Programmatic Control via `SuggestionsController` #

Use SuggestionsController to programmatically open, close, toggle, or select items:

final suggestionsController = SuggestionsController<User>();

// Open dropdown
suggestionsController.open();

// Close dropdown
suggestionsController.close();

// Toggle dropdown visibility
suggestionsController.toggle();

// Select an item programmatically
suggestionsController.select(user);

// Check if open
final isOpen = suggestionsController.isOpen;

// Pass to the widget:
PaginatedTypeAhead<User>(
  suggestionsController: suggestionsController,
  initialPage: 1,
  suggestionsCallback: (query, page) => fetchUsers(query, page),
  itemBuilder: (user) => ListTile(title: Text(user.name)),
  onSelected: (user) => handleSelect(user),
)

API Reference #