Changelog #

2.5.0 #

FIX: A SearchFieldTheme.divider taller than one pixel no longer overflows the item list. The overlay reserved a hardcoded 1.0 for any divider, but Flutter's Divider() — the widget almost everyone reaches for — is 16px tall, so a three-item searchable menu threw A RenderFlex overflowed by 15 pixels on the bottom
FIX: A DropdownTooltipTheme that sets one visual property no longer blanks the rest of the tooltip's box. Flutter's Tooltip treats a non-null decoration as a total replacement rather than a merge, so DropdownTooltipTheme(borderRadius: BorderRadius.circular(8)) produced a transparent tooltip — white text on nothing. The same held for shadow and borderColor alone. Unset slots now fall back to Tooltip's own defaults
FEAT: Added SearchFieldTheme.dividerHeight (defaults to 1.0). The overlay reserves this much space and constrains the divider to it, so the height reserved and the height drawn cannot disagree
FEAT: Added DropdownTooltipTheme.border, a BoxBorder — the same shape DropdownTheme.border and SearchFieldTheme.border take. It wins over borderColor / borderWidth
CHANGE: SearchFieldTheme.divider is now laid out at exactly dividerHeight. A caller passing Divider() and relying on its natural 16px must now pass dividerHeight: 16 to keep it; otherwise the divider draws at 1px instead of overflowing
CHANGE: A DropdownTooltipTheme that sets backgroundColor and nothing else now keeps Flutter's 4px tooltip corners, where it previously squared them off. Set borderRadius: BorderRadius.zero for the old look
DEPRECATED: DropdownTooltipTheme.borderColor and DropdownTooltipTheme.borderWidth in favour of border. They still work. Removed in 3.0.0
REFACTOR: SearchFieldTheme, DropdownScrollTheme and DropdownTooltipTheme resolve themselves, completing the work DropdownTheme began in 2.4.1. resolve() takes a plain value — a DropdownAmbientColors palette, a Brightness, or nothing — never a BuildContext, so every styling rule is a pure function. The last four Theme.of(context) calls and twelve ?? fallback chains left the widget's build()
CHANGE: Exported ResolvedSearchFieldStyle, ResolvedScrollStyle and ResolvedTooltipStyle, and added DropdownAmbientColors.hint. Additive; existing theme fields are unchanged
TEST: 107 tests, up from 77. Thirty-five exercise theme resolution with no widget tree at all. DropdownTooltipTheme had no test coverage of any kind before this release, which is why its bug survived

2.4.1 #

FIX: The trailing arrow now honours the single-item auto-disable. A dropdown disabled by disableWhenSingleItem blocked taps, switched its decoration to the disabled form and applied disabledTextStyle, while the arrow kept its enabled colour. Visible whenever hideIconWhenSingleItem: false. The icon asked widget.enabled; everything else asked isEnabled
DEPRECATED: DropdownTheme.animationDuration. Nothing has ever read it — the animation is driven by FlutterDropdownButton.animationDuration, and setting it on the theme was silently ignored. It is being removed rather than wired up: honouring it now would slow the animation for everyone who set it and has been living with the widget's 200ms. Pass the duration to the widget. Removed in 3.0.0
REFACTOR: DropdownTheme resolves itself. resolveButton(), resolveOverlay() and resolveItem() return styles whose slots are all filled in, and take a plain DropdownAmbientColors palette rather than a BuildContext — so styling rules are pure functions, testable without mounting a widget. Thirteen inline ?? fallback chains and fourteen Theme.of(context) calls left build(). SearchFieldTheme and DropdownScrollTheme are not converted yet
CHANGE: Exported DropdownAmbientColors, ResolvedButtonStyle, ResolvedOverlayStyle and ResolvedItemStyle. Additive; existing theme fields are unchanged
CHANGE: pubspec.yaml's description no longer advertises "specialized variants for different content types" — there has been one widget since 2.0.0
TEST: 77 tests, up from 50. Fourteen exercise theme resolution with no widget tree at all
DOCS: CLAUDE.md and documentation/ rewritten around the current architecture. api_reference.md documented five classes deleted in 2.0.0 (BaseDropdownButton, BasicDropdownButton, TextOnlyDropdownButton, DynamicTextBaseDropdownButton, DropdownItem) and never mentioned FlutterDropdownButton. Seventeen examples in theming.md and text_configuration.md called widgets that no longer exist; three passed theme: DropdownTheme(...) where a DropdownStyleTheme is required

2.4.0 #

FEAT: FlutterDropdownButton.text() now accepts a label callback, so text mode renders any type — not just String. Overflow handling, the tooltip and the default search filter all work off the label, so a List<User> no longer has to drop to itemBuilder and give those up. Omitting label for a non-String T now fails loudly at construction in debug builds instead of throwing a cast error at paint time
FEAT: Added DropdownOverlayController and DropdownOverlaySpec — hold a controller instead of mixing in DropdownMixin to build your own dropdown. It manages the overlay's lifetime, the open/close animation, and the "only one menu open" rule behind nine members rather than twenty-three, and can be tested without a State. See example/lib/pages/domain_type_page.dart
FEAT: Only-one-menu-open is now scoped to the enclosing Overlay rather than to the process, so two dropdowns in two different Overlays no longer close each other
FIX: FlutterDropdownButton.closeAll() now accepts animate, as README.md has documented since 2.2.1. The parameter existed only on DropdownMixin.closeAll(); the widget's facade never forwarded it, so the documented call did not compile
FIX: A dropdown menu that is already open now reflects items that change underneath it. Previously an item list arriving asynchronously never appeared until the user closed and reopened the menu
FIX: An open menu now grows when its item list gets longer, and flips above the button when the taller menu no longer fits below. Previously the height was fixed when the menu opened, so new items were pushed below the fold of a scrollbar that appeared for no visible reason
DEPRECATED: DropdownMixin is deprecated in favour of DropdownOverlayController. It still works — it now delegates to a controller, so mixin-based and controller-based menus share one registry and both answer closeAll(). It will be removed in 3.0.0
REFACTOR: _FlutterDropdownButtonState holds a controller instead of inheriting from a mixin. Fourteen one-line forwarders and the static _currentInstance global are gone
REFACTOR: The filtered item list is derived from the items and the query on read rather than cached in a field, removing four hand-written invalidation sites
TEST: 50 tests, up from 26 — placement geometry, search invalidation, overlay bounds and resizing, label extraction, and the controller itself (unit-tested with no widget tree)

2.3.2 #

FIX: Fixed dropdown menu rendering off-screen when the dropdown lives inside a nested Overlay or Navigator (side panels, shell routes, embedded views) — the button's position was resolved against the root view while the menu was placed against the enclosing Overlay's origin, shifting the menu by that Overlay's offset. Position and screen-bounds clamping now both use the Overlay's render box
FIX: Fixed searchable: true forcing a scrollbar on dropdowns whose items would otherwise fit — the search field's height was subtracted from the item area instead of being added to the overlay height. A 3-item searchable dropdown under default theming no longer scrolls
FIX: Fixed the search query being cleared whenever an ancestor widget rebuilt. didUpdateWidget compared items by list identity, so any caller passing a derived list (source.map(...).toList(), or a non-const literal) reset the query on every rebuild. The filter is now recomputed from the current query, which is correct regardless of the equality semantics of T
FIX: Fixed the dropdown overrunning screenMargin by buttonGap (4px) when opening downward, and reserving a double margin (16px) when shrinking to fit. The menu now keeps exactly one screenMargin from the safe-area edge in both cases — a menu constrained for space is ~4px taller than before
DEPRECATED: DropdownMixin.calculateMenuWidth() and DropdownMixin.calculateMenuLeftPosition() are deprecated in favour of resolvePlacement(), which returns the menu's full geometry in one call. They still work and will be removed in 3.0.0
REFACTOR: Extracted all overlay positioning geometry out of DropdownMixin into a pure module that takes plain values and returns plain values — no BuildContext, no MediaQuery, no State. DropdownMixin remains as the adapter that reads the screen and delegates
TEST: Added the package's first test suite — 26 tests, 17 of which exercise the positioning geometry without mounting a widget

2.3.1 #

FIX: Explicitly set mouseCursor on InkWell widgets to restore hover cursor behavior on web/desktop after recent Flutter versions changed the default MaterialStateMouseCursor.clickable resolution
FIX: Dropdown button now shows SystemMouseCursors.click when enabled and SystemMouseCursors.forbidden when disabled (matches HTML <button disabled> cursor: not-allowed convention)
FIX: Dropdown items now consistently show SystemMouseCursors.click on hover

2.3.0 #

FEAT: Added DropdownTheme.disabledBackgroundColor for the dropdown button background when disabled
FEAT: Added DropdownTheme.disabledBorder for the dropdown button border when disabled
FEAT: Added DropdownTheme.disabledButtonDecoration for a full custom button decoration when disabled (takes precedence over disabledBackgroundColor / disabledBorder)
FEAT: Added TextDropdownConfig.disabledTextStyle for styling the button text (both value and hint) when disabled — merged over the base textStyle / hintStyle
FEAT: Added "Disabled Styling" section to the example playground to live-preview the new options (toggle enabled: false to see the effect)

2.2.1 #

FIX: Fixed closeAll() not resetting trailing icon rotation and internal state — overlay was removed but _overlayEntry, animation controller, and setState were not handled, leaving the icon in the open (rotated) state
FIX: Fixed openDropdown() not closing the previously open dropdown when another dropdown is opened, which could leave orphaned overlays
FEAT: Added animate parameter to closeAll() — defaults to true for animated close with icon rotation, set to false for immediate removal before navigation

2.2.0 #

FEAT: Added searchable dropdown support with real-time item filtering
FEAT: Added searchable parameter to enable search text field at the top of the dropdown overlay
FEAT: Added searchFilter parameter for custom filter logic (required for custom mode, optional for text mode with default case-insensitive contains matching)
FEAT: Added emptyBuilder parameter for customizing the empty state when search yields no results
FEAT: Added SearchFieldTheme class for comprehensive search field styling (text style, cursor, colors, border, padding, margin, border radius, divider, keyboard type, text input action, and more)
FEAT: Added search field to DropdownStyleTheme for centralized search field theming
FEAT: Dynamic overlay height — dropdown shrinks to fit filtered results instead of keeping fixed height
FEAT: Auto-reset search query on item selection, outside-tap dismissal, and dropdown reopen
FEAT: Added rebuildOverlay() method to DropdownMixin for triggering overlay rebuilds
CHANGE: DropdownMixin overlay container now uses BoxConstraints(maxHeight:) instead of fixed height to support dynamic content sizing

2.1.0 #

FEAT: TextDropdownConfig.textAlign now controls item alignment in the dropdown menu and button (previously hardcoded to left-align)
FEAT: Supports TextAlign.center, TextAlign.end, TextAlign.right for both menu items and selected value display

2.0.0 #

BREAKING: Unified all dropdown variants into a single FlutterDropdownButton<T> widget
BREAKING: Removed BasicDropdownButton, TextOnlyDropdownButton, DynamicTextBaseDropdownButton (use FlutterDropdownButton and FlutterDropdownButton.text instead)
BREAKING: Removed DropdownItem<T> model class (use itemBuilder callback instead)
BREAKING: Removed BaseDropdownButton and BaseDropdownButtonState (no longer needed as public API)
BREAKING: Removed TextDropdownRenderMixin (absorbed into FlutterDropdownButton)
BREAKING: Removed deprecated showSeparator and separator parameters (use DropdownTheme.itemBorder instead)
FEAT: FlutterDropdownButton<T>() default constructor with itemBuilder for custom widget rendering (replaces BasicDropdownButton)
FEAT: FlutterDropdownButton<T>.text() named constructor for text-only dropdowns (replaces both TextOnlyDropdownButton and DynamicTextBaseDropdownButton)
FEAT: width is now optional in text mode — omit for content-based dynamic width, provide for fixed width
FEAT: All features (leading, disableWhenSingleItem, expand, etc.) available in a single widget
FEAT: FlutterDropdownButton.closeAll() static method for manual dropdown cleanup
MIGRATION: BasicDropdownButton(items: [DropdownItem(value: v, child: w)]) → FlutterDropdownButton(items: [v], itemBuilder: (item, isSelected) => w)
MIGRATION: TextOnlyDropdownButton(items: items, width: 200) → FlutterDropdownButton.text(items: items, width: 200)
MIGRATION: DynamicTextBaseDropdownButton(items: items) → FlutterDropdownButton.text(items: items, disableWhenSingleItem: true)

1.6.1 #

FIX: Removed disabled opacity override that forced 0.6 opacity on single-item dropdowns, preserving original button styling

1.6.0 #

BREAKING: TextOnlyDropdownButton.width is now required (fixed-width dropdown by design)
BREAKING: Removed minWidth, maxWidth, expand from TextOnlyDropdownButton (use DynamicTextBaseDropdownButton for content-based width)
BREAKING: Removed width from DynamicTextBaseDropdownButton (content-based width by design, use minWidth/maxWidth for constraints)
FEAT: Added disableWhenSingleItem parameter to DynamicTextBaseDropdownButton for toggling single-item non-interactive mode (defaults to true)
FEAT: Added showTrailing getter to BaseDropdownButtonState allowing subclasses to conditionally hide the trailing icon
FEAT: DynamicTextBaseDropdownButton now auto-selects the only item when in single-item disabled mode
FIX: Fixed DynamicTextBaseDropdownButton single-item mode not blocking tap interactions (was using widget.enabled instead of isEnabled)
FIX: Fixed disabled opacity check using widget.enabled instead of isEnabled, causing incorrect visual state for dynamic dropdowns
FIX: Removed duplicated build() and _applyWidthConstraints() in DynamicTextBaseDropdownButton (was missing expand support)
REFACTOR: Extracted common text rendering logic into TextDropdownRenderMixin to eliminate duplication between TextOnlyDropdownButton and DynamicTextBaseDropdownButton
REFACTOR: Replaced example showcase app with interactive Playground for live parameter configuration

1.5.5 #

FIX: Fixed overlay removal crash when dropdown is closed during widget disposal by adding mounted check and error handling to closeDropdown()

1.5.4 #

FIX: Fixed scroll gradient direction - top gradient now properly fades from opaque to transparent downward, bottom gradient fades from transparent to opaque downward

1.5.3 #

FIX: Fixed ScrollbarTheme colors not being applied by correcting widget hierarchy (ScrollbarTheme must wrap Scrollbar, not vice versa)

1.5.2 #

PERF: Improved scroll performance with many items by using ListView.builder (lazy loading) and ClampingScrollPhysics (removes bouncing effect)
FIX: Fixed dropdown height calculation to account for safe areas (status bar, navigation bar, home indicator)

1.5.1 #

FIX: Fixed dropdown overlay remaining visible after screen transitions by immediately removing overlay on dispose without animation
FIX: Added safe error handling for overlay removal to prevent crashes when overlay has already been removed
FEAT: Added DropdownMixin.closeAll() static method for manual dropdown cleanup before navigation or other actions

1.5.0 #

BREAKING: Extracted tooltip styling from TextDropdownConfig into new TooltipTheme class for better separation of concerns
BREAKING: Removed tooltip styling properties from TextDropdownConfig (tooltipBackgroundColor, tooltipTextColor, tooltipTextStyle, tooltipDecoration, tooltipBorderRadius, tooltipBorderColor, tooltipBorderWidth, tooltipShadow, tooltipPadding, tooltipMargin, tooltipConstraints, tooltipTextAlign)
FEAT: Added TooltipTheme class for centralized tooltip visual styling
FEAT: Added tooltip field to DropdownStyleTheme to include TooltipTheme alongside DropdownTheme and DropdownScrollTheme
CHANGE: TextDropdownConfig now only controls tooltip behavior (enableTooltip, tooltipMode, durations, positioning, trigger modes)
MIGRATION: Move tooltip styling properties from TextDropdownConfig to TooltipTheme in DropdownStyleTheme

1.4.8 #

FEAT: Added itemBorder property to DropdownTheme for applying borders to individual dropdown items (commonly used for bottom borders between items)
FEAT: Added excludeLastItemBorder property to DropdownTheme to exclude border from the last item (defaults to true for clean design)
DEPRECATED: showSeparator and separator parameters are now deprecated in favor of itemBorder (will be removed in 2.0.0)

1.4.7 #

FEAT: Added minMenuWidth parameter to set minimum dropdown menu width independently from button width
FEAT: Added maxMenuWidth parameter to set maximum dropdown menu width independently from button width
FEAT: Added menuAlignment parameter (left/center/right) to control menu positioning when menu is wider than button

1.4.6 #

FEAT: Added showSeparator and separator parameters to display customizable dividers between dropdown items (defaults to Divider widget)

1.4.4 #

FIX: Fixed hover color not visible when selectedItemColor is set by changing Container to Ink widget for proper Material effect layering

1.4.3 #

FEAT: Added trailing parameter support to DynamicTextBaseDropdownButton (static display for single-item mode, rotation animation for multi-item mode)

1.4.2 #

FEAT: Added buttonHoverColor, buttonSplashColor, and buttonHighlightColor to DropdownTheme for controlling dropdown button InkWell interaction colors
FEAT: Added buttonHeight property to DropdownTheme for independent button content height control from iconSize, with automatic overflow prevention
FEAT: Added trailing parameter to BaseDropdownButton for customizing the dropdown arrow icon with automatic rotation animation

1.4.1 #

FEAT: Added hover cursor support - dropdown button now shows click cursor on mouse hover using InkWell

1.4.0 #

BREAKING: Changed leadingBuilder to leading and selectedLeading parameters in DynamicTextBaseDropdownButton for better performance and simpler API
BREAKING: Renamed leadingWidgetPadding to leadingPadding in DynamicTextBaseDropdownButton for consistent naming
PERF: Optimized AnimatedBuilder in DropdownMixin to prevent unnecessary rebuilds of overlay content during animations (60+ rebuilds eliminated per dropdown open/close)
PERF: Changed leading widget API from builder function to direct widget parameters, eliminating redundant widget creation (126+ widget creations reduced to 2 per dropdown)

1.3.3 #

FEAT: Added expand parameter to automatically wrap dropdown in Expanded widget for flex layouts, with spaceBetween alignment when expanded

1.3.2 #

FEAT: Added smart tooltip support with overflow detection, auto-positioning, and extensive customization options (background color, border, shadow, text styling, trigger modes, and timing controls)
FIX: Fixed text and icon vertical alignment issue by adding centerLeft alignment to text and center crossAxisAlignment to Row, and fixed mainAxisAlignment to use spaceBetween when width is fixed

1.3.1 #

FEAT: Added leadingBuilder property to DynamicTextBaseDropdownButton for displaying custom widgets (icons, images) before text
FEAT: Added leadingWidgetPadding property to DynamicTextBaseDropdownButton for controlling leading widget spacing

1.3.0 #

FEAT: Added DynamicTextBaseDropdownButton widget that adapts behavior based on item count (non-interactive when single item, normal dropdown when multiple items)
FEAT: Added hideIconWhenSingleItem property to DynamicTextBaseDropdownButton for controlling icon visibility in single-item mode
FEAT: Added interactive example demo with real-time item add/delete functionality
FIX: Fixed dropdown button height consistency issue by wrapping Text and Icon in SizedBox with fixed height based on iconSize
FIX: Fixed mainAxisAlignment from spaceBetween to start to allow button width to fit content size within maxWidth constraint

1.2.3 #

FEAT: Added scrollToSelectedItem property to automatically scroll to the currently selected item when dropdown opens (defaults to true)
FEAT: Added scrollToSelectedDuration property for controlling scroll animation duration (null for instant jump, duration value for smooth animation)
FEAT: Improved scrollable dropdown UX by automatically positioning selected items in view when there are many items

1.2.2 #

FEAT: Added icon property to DropdownTheme for customizing dropdown arrow icon (supports any IconData)
FEAT: Added iconSize property to DropdownTheme for controlling dropdown icon size
FEAT: Added iconDisabledColor property to DropdownTheme for customizing icon color in disabled state
FEAT: Added iconPadding property to DropdownTheme for controlling spacing between selected value and icon
FEAT: Added overlayPadding property to DropdownTheme for controlling internal spacing of the dropdown menu container

1.2.1 #

FIX: Fixed dropdown overlay border rendering issue by removing Material borderRadius that conflicted with Container border decoration
FIX: Fixed dropdown icon not updating on open/close state change and added rotation animation
REFACTOR: Reorganized theme files into theme/ subdirectory for better code organization

1.2.0 #

FEAT: Added thumbWidth and trackWidth properties to DropdownScrollTheme for independent scrollbar thumb and track width control
FEAT: Added iconColor property to DropdownTheme for customizing dropdown arrow icon color
FIX: Fixed dropdown overlay content clipping issue with border radius by adding clipBehavior to Material widget
FIX: Changed theme parameter type from Object? to DropdownStyleTheme? for better type safety
FIX: Fixed dropdown menu height calculation to properly account for itemMargin and border thickness, preventing unnecessary scrollbars

1.1.0 #

FEAT: Added DropdownScrollTheme for customizing scrollbar appearance
FEAT: Added DropdownStyleTheme as main theme container for dropdown and scroll themes
FEAT: Support for custom scrollbar colors, thickness, radius, and visibility options
REFACTOR: Updated example app with feature-based showcase and style selector

1.0.1 #

FEAT: Added itemMargin property to DropdownTheme for controlling spacing between dropdown items
FEAT: Added itemBorderRadius property to DropdownTheme for individual item border radius styling
FEAT: Added hover effect support to TextOnlyDropdownButton with InkWell integration
FIX: Fixed hover effect positioning to respect itemMargin boundaries for consistent visual feedback
REFACTOR: Added BaseDropdownButton abstract class to reduce code duplication between dropdown variants
FEAT: Exported BaseDropdownButton for creating custom dropdown implementations

1.0.0 #

FEAT: Initial release with BasicDropdownButton and TextOnlyDropdownButton widgets
FEAT: Smart dropdown positioning - automatically opens upward when insufficient space below
FEAT: Dynamic height adjustment to prevent screen overflow
FEAT: OverlayEntry-based dropdown with smooth animations and outside-tap dismissal
FEAT: Dynamic width support (width, maxWidth, minWidth parameters)
FEAT: Shared DropdownTheme system for consistent styling across variants
FEAT: TextDropdownConfig for precise text overflow control (ellipsis, fade, clip, visible)
FEAT: Multi-line text support and custom text styling
FEAT: Generic DropdownItem model supporting any widget content
FEAT: DropdownMixin for shared functionality across dropdown variants
FEAT: Comprehensive example app with multiple dropdown demonstrations

flutter_dropdown_button 2.5.0 flutter_dropdown_button: ^2.5.0 copied to clipboard

Metadata