animated_custom_dropdown

The biggest release yet. A brand-new overlay animation system, infinite-scroll pagination, a stack of new customization options, and fixes that clear most of the open-issue backlog. Every change is backward-compatible — upgrade without touching your code.

yaml
dependencies:
animated_custom_dropdown: ^4.0.0

🌟 Highlights

Configurable open/close animations

Pick a transition, tune the timing, or bring your own — all through one animation object.

CustomDropdown(
items: items,
animation: CustomDropdownAnimation(
type: DropdownAnimationType.scaleFade, // size · fade · sizeFade · scale · scaleFade · slide
duration: Duration(milliseconds: 300),
curve: Curves.easeOutCubic,
staggerItems: true, // cascading list-item entrance
),
onChanged: (v) {},
)

• 6 built-in, direction-aware transitions + smoother default curves
• Optional staggered item entrance, and an animated open/close arrow
• CustomDropdownAnimation.none to disable, or a builder for a fully custom transition

Infinite scroll (pagination)

Lazy-load remote data page by page — no more fetching everything up front.

CustomDropdown.searchRequest(
paginatedRequest: (query, page) => api.users(query, page), // 1-based page
pageSize: 20,
loadMoreIndicator: const Center(child: CircularProgressIndicator()),
onChanged: (v) {},
)
Loads the first page on open, appends the next as you scroll, and stops when a page returns fewer than pageSize items. The classic one-shot futureRequest keeps working unchanged.

✨ New

• Floating label — labelText (String) or a fully custom label (Widget), with labelStyle / floatingLabelStyle / floatingLabelBehavior / floatingLabelGap
• textAlign across header, hint, items, search input, no-result text and label
• canClearSelection — clear button to reset to empty/hint
• searchRequestMinChars — gate the request until N characters
• selectOnItemTap — let your listItemBuilder own selection (e.g. disabled items)
• overlayDirection — auto / below / above
• initiallyOpen — open on first build
• autofocusOnSearch — focus the search field (and raise the keyboard) on open
• Controller helpers — SingleSelectController.select(), MultiSelectController.select() / toggle()
• CustomDropdownDecoration.closedHeaderHeight — fixed, centered closed-field height

🐛 Fixes

• Overlay hidden behind the keyboard while searching — now repositions and scrolls into view (#116, #113, #51, #21)
• Theme bleed-through on Flutter 3.35+ — double border, opaque/gray background, gray-on-error and bottom underline are gone (#115, #117, #110, #97, #84, #86, #68)
• overlayController ignored when a new instance is supplied on rebuild (#114)
• SchedulerPhase assertion / setState-after-dispose on overlay teardown and async search (#96, #101)
• "No result found" reliability, unmodifiable-list safety, and custom-item tap handling — verified and test-locked (#112, #62, #89, #72)

⬆️ Upgrading

• No code changes required. Nothing was removed or renamed; new options are opt-in and defaults preserve existing behavior. (The only signature tweak: the search-request constructors now accept exactly one of futureRequest / paginatedRequest.)
• You'll notice the theme fixes, smoother animation curves and the rotating arrow — all improvements, no action needed.
• Minimum Flutter is now 3.19 (the package uses WidgetStateProperty, OverlayPortal, View.of and Dart 3 features).

🙌 Thanks

@hamhoney (#90), @antoniomtnez (#109), @Giovanny-DS (#108) and @mreslamgeek (#94) for PRs and reports — and everyone who filed issues that shaped this release.

Full changelog: see CHANGELOG.md (https://github.com/AbdullahChauhan/custom-dropdown/blob/master/CHANGELOG.md).

A big release: a new overlay animation system, infinite-scroll pagination, a stack of new customization options, and fixes that sweep most of the open-issue backlog. All additions are backward-compatible.

✨ New features

• Overlay animations — configure the open/close transition via the new animation parameter (CustomDropdownAnimation):
  • Built-in transitions: size, fade, sizeFade (default), scale, scaleFade, slide — direction-aware (open up/down).
  • Tune duration, reverseDuration, curve, reverseCurve; smoother defaults (easeOutCubic open / easeInCubic close).
  • CustomDropdownAnimation.none to disable, or a builder escape hatch for any custom transition.
  • Optional staggered list-item entrance via staggerItems (tune with itemStagger / itemDuration).
  • The dropdown arrow now rotates (down ↔ up) in sync with open/close.
• Infinite scroll / pagination for the search-request constructors — new paginatedRequest: (query, page) => …:
  • Loads page 1 on open/search and appends the next page as you scroll near the bottom, stopping once a page returns fewer than pageSize items (default 20).
  • Optional loadMoreIndicator footer. Provide exactly one of futureRequest / paginatedRequest.
• Material-style floating label — labelText (String) or a fully custom label (Widget), with CustomDropdownDecoration.labelStyle / floatingLabelStyle / floatingLabelBehavior / floatingLabelGap (spacing between the floated label and the field) (#111).
• textAlign for the header, hint, list items, search input, "no result found" text and the floating label (#71; thanks @hamhoney for PR #90).
• canClearSelection — a clear button to reset back to the empty/hint state (#106, #83).
• searchRequestMinChars — don't fire the request until at least N characters are typed (#107).
• selectOnItemTap — let a custom listItemBuilder own item selection (#80; inspired by PR #108 from @Giovanny-DS).
• overlayDirection (auto / below / above) to force the side the overlay opens towards (#92).
• initiallyOpen to open the overlay automatically on first build (#87).
• autofocusOnSearch to focus the search field (raising the keyboard) when the overlay opens (#70).
• Controller selection helpers: SingleSelectController.select(), MultiSelectController.select() and MultiSelectController.toggle() (#100).
• CustomDropdownDecoration.closedHeaderHeight for a fixed, vertically-centered closed-field height (#105).

💅 Improvements

• The default closed error border now follows errorStyle.color, so the border and error text match without setting closedErrorBorder explicitly (#105).
• Search a list of custom class instances out of the box — search matches each item's toString(); use the CustomDropdownListFilter mixin for complex filtering (#103).

🐛 Fixes

• Overlay hidden behind the on-screen keyboard while searching (#116, #113, #51):
  • Flips above the field using the live keyboard inset, recalculates on keyboard show/hide (didChangeMetrics), keeps the dropdown alive (AutomaticKeepAliveClientMixin) and scrolls its field back into view — so the overlay no longer disappears when the field sits in a scrollable that resizes for the keyboard.
• Double border, opaque/gray background, extra side padding and bottom underline when an inputDecorationTheme is set (Flutter 3.35+), including the gray background shown on validation error (#115, #117, #110, #68, #86, #84, #97; also raised in PR #94 by @mreslamgeek):
  • The field's internal InputDecorator no longer inherits the ambient inputDecorationTheme; it only surfaces the form validation error text.
• overlayController ignored when a different controller instance is supplied on rebuild (#114) — the overlay now re-binds to the latest controller.
• SchedulerPhase assertion on dismiss, and a stale-callback crash when a search request completes after the field is disposed (#96, #101; thanks @antoniomtnez for PR #109).
• multiSelectSearchRequest reliably shows "No result found" after an empty search result (#112).
• Selecting/deselecting no longer mutates a caller's unmodifiable items/initialItems list (#62).

🙌 Thanks

Thanks to @hamhoney (#90), @antoniomtnez (#109), @Giovanny-DS (#108) and @mreslamgeek (#94) for PRs and reports.

• Fix: onChanged not invoked after first invocation (Thanks @ravindrabarthwal for PR)

• Add: Controllers support (Thanks @hbatalhaStch for PR)
  • SingleSelectController
  • MultiSelectController
• Add: Enabled/Disabled state support (Thanks @KabaDH for PR)
• Add: Dropdown disabled state decoration support
  • CustomDropdownDisabledDecoration
• Add: Items list scroll controller support
  • itemsScrollController
• Add: Dropdown overlay controller support
  • overlayController
• Add: Dropdown visibility status callback
  • visibility
• Update: Enhance decoration support
  • prefixIcon
• Remove: Empty items list assertion (Thanks @hbatalhaStch for the issue)

• Add: Multi selection support (Thanks @KabaDH for PR)
  • CustomDropdown.multiSelect
  • CustomDropdown.multiSelectSearch
  • CustomDropdown.multiSelectSearchRequest
• Add: Decoration support
  • CustomDropdownDecoration
    • SearchFieldDecoration
    • ListItemDecoration
    • ScrollbarThemeData
• Add: Dropdown overlay height support (Thanks @aguilastorm for PR)
  • overlayHeight
• Add: Custom loading widget for search request
  • searchRequestLoadingIndicator
• Add: Padding properties:
  • closedHeaderPadding
  • expandedHeaderPadding
  • itemsListPadding
  • listItemPadding
• Fix: Stop the scrolling and dropdown should remains in expanded state (Thanks @s-saens for PR)
• Breaking: Properties move inside decoration:
  • closedFillColor
  • expandedFillColor
  • errorStyle
  • closedBorder
  • closedBorderRadius
  • expandedBorder
  • expandedBorderRadius
  • closedErrorBorder
  • closedErrorBorderRadius
  • closedSuffixIcon
  • expandedSuffixIcon

• Add: Migration to support List of generatic type T (Thanks @JesusHdez960717 for PR)
• Add: Mixin CustomDropdownListFilter for complex filter on search field
• Add: Builders support
  • listItemBuilder
  • headerBuilder
  • hintBuilder
  • noResultFoundBuilder
• Add: validator & validateOnChange to enhance form validation support
• Add: Other new properties:
  • initialItem
  • searchHintText
  • expandedBorder
  • expandedBorderRadius
  • errorBorderRadius
  • hideSelectedFieldWhenExpanded
  • noResultFoundText
  • expandedFillColor
  • expandedSuffixIcon
  • maxlines
• Breaking: Clean controller support
• Breaking: Clean listItemStyle support
• Breaking: Clean selectedStyle support
• Breaking: Clean errorText support
• Breaking: fillColor change to closedFillColor
• Breaking: fieldSuffixIcon change to closedSuffixIcon
• Breaking: errorBorderSide change to errorBorder
• Breaking: borderSide change to closedBorder
• Breaking: borderRadius change to closedBorderRadius
• Refactor: Overlay rendering approach (change to declarative)

• Add: Request delay support for Search request API (Thanks @JesusHdez960717 for PR)

• Add: Search request API (Search on provided request)
• Update readme.

• Update: Flutter version 3.3.9 changes
• Add: List item builder support (Thanks @Mohamed25885 for PR)

• Update: Flutter version 3.0.1 changes

• Fix: State dispose calls

• Add: Search field (Search on list data)
• Fix: State mounted check on dropdown open or close.
• Update readme.

• Update: Suffix icon only allowed for dropdown field.
• Fix: Empty list pass (assert added).

• Add: Dropdown overlay alignments (top, bottom) according to available screen space.
• Update readme.

• Update readme, project description. Format files.

• Customizable animated dropdown widget. </content> </invoke>