flutter_floating_bottom_bar 3.0.1

An adaptable Flutter floating bottom bar for navigation, search, and custom widgets, with scroll-aware visibility and accessible interactions.

Unreleased

3.0.1

• Allow compatible 1.x releases of material_ui and cupertino_ui, including their latest versions on Flutter 3.47, while retaining Flutter 3.44 support.
• Fix BottomBarItem growing to fill the screen height when used inside a BottomBar, which turned BottomBarItems bars into full-height cards. Items in an explicitly sized BottomBarItems row still fill its height.
• Fix avoidKeyboard remounting the bar when the keyboard opened, which dropped focus from text fields in BottomBar.child and closed the keyboard.
• Fix the hidden action remounting on every hide/show, which reset state in a custom icon, and stop the action taking focus while the bar is visible.
• Fix the hidden bar peeking above the screen edge when layout.offset, the bottom safe area or the keyboard lift exceeded the slide distance. For BottomBarTransition.slide, slideStart is now measured from the edge the bar slides toward, so the default Offset(0, 2) always clears it. slideAndFade keeps its offset relative to the bar's resting position.
• Fix taps and accessibility bounds lagging behind a bar that is sliding in.
• Fix the bar hiding again after a fling to the top on bouncing scroll physics: overscroll and its spring-back no longer count as scrolling, and a scroll that comes to rest at the start shows the bar (unless reverse).

3.0.0

Breaking

• Requires Dart >=3.12.0 and Flutter >=3.44.0.
• Material imports now come from package:material_ui/material_ui.dart. Apps still using the in-SDK Material must migrate their Material imports and theme to material_ui; migrated apps no longer need MaterialUiCompatibilityBridge for this package.
• BottomBarLayout and BottomBarLayout.adaptive now default borderRadius to 28. Pass BorderRadius.zero for a square bar.

Added

• BottomBarLayout.avoidKeyboard (default true): pads the bar and hidden action by MediaQuery.viewInsets.bottom so they sit above the on-screen keyboard when the host hasn't already consumed it (e.g. Scaffold(resizeToAvoidBottomInset: false)). No-op when insets are already zero, and does not affect BottomBarScope.barHeight or BottomBarBodyPadding.
• BottomBarController.reportScroll({required double delta}): drives the bar's threshold/reverse/hideOnScroll visibility rules from a scroll source that never emits ScrollNotifications, such as an embedded WebView. Visibility-only — it does not affect scrollToStart()/scrollToEnd(), which still require a real ScrollPosition.
• BottomBarLabelBehavior (alwaysShow, onlySelected, alwaysHide) and BottomBarItems.labelBehavior: controls when descendant BottomBarItem labels render. Exposed to BottomBarItem via the new public BottomBarItemsScope inherited widget; items outside a BottomBarItems row keep the alwaysShow default.
• BottomBarScrollBehavior.keepVisibleOnFocus (default true): skips scroll-driven hide while the floating BottomBar.child holds focus, so a search field or composer in the bar isn't hidden mid-scroll while the user is typing. BottomBarController.hide() still hides the bar regardless of focus; the bar is not auto-shown on focus.

Changed

• In bounded rows wide enough for each item's 48x48 minimum target, BottomBarItems wraps every child in Expanded, so items share the row's width equally. Narrow bounded rows use a horizontal scroll view to preserve the minimum targets; unbounded rows keep their raw children. A BottomBarItem's Text label (with non-null data) is truncated to a single line with an ellipsis; Text.rich and other label widgets are unaffected.

• Migrated from package:flutter/material.dart to the standalone material_ui package. Material was decoupled from the Flutter SDK in 3.47; the in-SDK copy is frozen to contributions and scheduled for removal. Apps that have already migrated no longer need MaterialUiCompatibilityBridge on account of this package — without it, the bar resolved Theme.of(context).colorScheme against the framework Material and silently fell back to a default theme.

• Minimum SDK constraints raised to Dart 3.12 / Flutter 3.44, which is what material_ui requires.

• Attaching a BottomBarController to a second bar now throws a FlutterError in debug builds as well, instead of an AssertionError.

• BottomBarLayout and BottomBarLayout.adaptive now default borderRadius to 28 so passing layout: no longer squares the bar. Pass BorderRadius.zero to opt out.

Fixed

• Hidden bar descendants are excluded from keyboard focus, so a TextField in the floating child cannot be tab-focused while the bar is hidden.

2.1.0

Added

• BottomBarLayout.maxWidth and BottomBarLayout.adaptive(maxWidth: ...) for width-capped adaptive layouts, plus copyWith(clearMaxWidth: true) for returning a derived layout to an uncapped width.
• BottomBarBodyPadding as the built-in way to reserve the live floating-bar footprint inside BottomBar.body.
• BottomBarScrollBehavior.showAtStart and BottomBarScrollBehavior.showOnScrollEnd for settling-based visibility restoration.

Changed

• BottomBarScope.barHeight now reflects the full rendered footprint reserved by the bar, including configured offset and bottom safe-area when enabled.
• BottomBarItem accessible naming is now deterministic: semanticLabel wins, otherwise tooltip, otherwise descendant semantics. Explicit names exclude descendant semantics to avoid duplicate announcements; items also expose selected/enabled button state, keep a 48x48 minimum target, and place badges at the directional top-end in both LTR and RTL layouts.
• Custom BottomBarMotion.transitionBuilder usage is documented as a paint-only contract that must preserve layout footprint.
• The hidden action is direction-aware by default: glyph, tooltip, and semantics flip with scrollOpposite, the touch target stays at least 48x48 when active, and the default glyph color follows ColorScheme.onPrimary.
• Hidden bar actions are non-interactive and excluded from semantics when the bar is visible.
• Reduced-motion environments snap directly to the target shown/hidden state instead of animating.
• BottomBarController ownership is strict: double-attach fails in debug and release, and visibility updates are accepted only from the owning bar.
• BottomBarController boundary scrolling now documents and uses explicit start/end semantics independent of scrollOpposite.

Fixed

• BottomBarController.scrollToStart() always targets ScrollPosition.minScrollExtent, and scrollToEnd() always targets ScrollPosition.maxScrollExtent.
• NestedScrollView boundary scrolling now targets the correct coordinated controller so start/end actions reset both header and body as expected.
• Large iconOffset values keep the hidden action tappable because hit testing now follows the translated visual position.
• The hidden action's full 48x48 minimum target now accepts taps at its corners; circular clipping applies only to the animated visual.
• The example web app now uses Flutter's current generated bootstrap and package-specific, orientation-neutral PWA metadata.

2.0.2

• Fix: BottomBarController.scrollToStart() (and the back-to-top icon) did not fully reset a NestedScrollView — the collapsed SliverAppBar/FlexibleSpaceBar stayed collapsed and the list landed below its true top. A NestedScrollView scrolls on two coordinated positions (an outer header and an inner body), but the bar only animated the most-recently-active one. The controller now detects an enclosing NestedScrollView and drives its shared scroll coordinator with a single call — animating the outer controller to the top (which pulls the inner body up with it) for scrollToStart, and the inner controller to the bottom (which collapses the header) for scrollToEnd. (#21)

2.0.1

• Fix: the back-to-top icon became unclickable when a large iconOffset was set. The icon was painted at the offset position but its SafeArea ancestor still hit-tested against the original (untranslated) rect, so a large offset moved the visible icon outside its tappable area. The offset now wraps the icon's SafeArea so hit-testing follows the painted position. (#19)

2.0.0

Major release. Breaking changes — see the migration table in README.md.

Breaking:

• Dart SDK minimum is now >=3.5.0 because the package uses Motor-backed motion.
• BottomBar.body is now Widget instead of Widget Function(BuildContext, ScrollController). The bar listens to ScrollNotification from any descendant scrollable; you no longer wire a controller through the builder.
• The barColor, width, offset, borderRadius, barAlignment, fit, clip, and respectSafeArea parameters moved into BottomBarLayout.
• The duration, curve, start, and end parameters moved into BottomBarMotion. BottomBarMotion() now defaults to Cupertino spring motion; existing BottomBarMotion(duration: ..., curve: ...) calls remain curve-based. start/end (doubles) are now slideStart/slideEnd (Offsets).
• The hideOnScroll, reverse, scrollOpposite, and scrollDeltaThreshold parameters moved into BottomBarScrollBehavior. scrollDeltaThreshold is now deltaThreshold.
• The iconWidth, iconHeight, iconDecoration, and barDecoration parameters moved to BottomBarThemeData (per-instance overrides remain via the theme: argument).
• BottomBarScrollControllerProvider is replaced by BottomBarScope. The scrollController field is gone; new fields are barHeight and isVisible.
• The hardcoded Colors.black default is replaced with Material 3 colorScheme.surfaceContainer for the bar and colorScheme.primary for the icon.

New:

• Motor-backed Cupertino motion is the default show/hide engine, with velocity-preserving redirection when scroll direction changes mid-animation.
• BottomBarMotion.cupertino(...), BottomBarMotion.curved(...), and BottomBarMotion.motor(...) constructors.
• BottomBarThemeData ThemeExtension for app-wide defaults.
• BottomBarTransition enum (slide, fade, scale, slideAndFade) plus BottomBarMotion.transitionBuilder.
• BottomBarItem and BottomBarItems helpers for the common nav-item case.
• BottomBarScope.barHeight exposes the live rendered bar height to descendants for content-padding purposes.
• BottomBarScope.isVisible exposes live visibility without owning a controller.
• Notification-based scroll detection works with NestedScrollView, CustomScrollView, multiple TabBarView children, and any user-supplied ScrollController with no wiring.
• BottomBarScrollBehavior.predicate for filtering unwanted notifications.
• BottomBarController now asserts on double-attach in debug.

Repository:

• Package source moved from packages/flutter_floating_bottom_bar/ to repo root. The example app moved to example/. The packages/ directory is removed.

1.4.0

• Upgrade project/tooling for Flutter 3.41.4 development via FVM.
• Update SDK constraints and refresh dependencies.
• Add BottomBarController for programmatic show, hide, toggle, scrollToStart, and scrollToEnd.
• Add onVisibilityChanged callback for visibility state transitions.
• Add scrollDeltaThreshold to reduce flicker from minor scroll movement.
• Add iconSemanticLabel and iconTooltip for better accessibility.
• Improve internal scroll/visibility handling and test coverage.

1.3.0

• Added respectSafeArea property to control whether the BottomBar should respect the safe area.
• Removed deprecated alignment property (use barAlignment instead).
• Fixed ScrollController issues with multiple attachments.
• Improved scroll listener management for better performance.

1.2.1+1

• Fix code formatting.

1.2.1

• Update to Flutter 3.22.1.
• Fix divider error in example.
• Update dependencies.

1.2.0

• Add offset, barAlignment, barDecoration, and iconDecoration properties.
• Remove bottom property.
• Deprecate alignment in favor of barAlignment.
• Update all code examples and fix errors.

1.1.0

• Add clip property to support clip behavior.
• Add an example for a bar with a FAB.

1.0.1

• Support Flutter 3.10.5.
• Update dependencies.

1.0.0+1

• Add documentation.

1.0.0

• Initial release with basic functionality.