flutter_floating_bottom_bar 3.1.0
flutter_floating_bottom_bar: ^3.1.0 copied to clipboard
An adaptable Flutter floating bottom bar for navigation, search, and custom widgets, with scroll-aware visibility and accessible interactions.
Unreleased #
3.1.0 #
Selection and indicator #
- Add a selection indicator to
BottomBarItems. SetselectedIndexandonSelectedand pickBottomBarIndicator.pill(),.tint(),.underline(),.dot()or.builder(). It slides between items on a spring, carries its momentum when retargeted, follows resizes and label changes in the same frame, scrolls a narrow row to the selected item, and jumps under reduced motion. The pill, tint and underline show the selected colour only where they cover an item, so labels change colour as the indicator passes.BottomBarItemtakes its selection from the row when one is set.
Item theme #
- Add
BottomBarItemThemeData, set asBottomBarThemeData.items, to style and animateBottomBarItemwithout forking it: colours, icon sizes, label styles, padding, icon-label gap, ink radius, overlay, splash and apressedScalepress effect. It also sets the default indicator and indicator motion forBottomBarItems, andBottomBarIndicator.none()opts a row out.BottomBarnow passes its resolved theme to its child. Selection changes animate colour, icon and label style on a spring,onlySelectedlabels grow in with the indicator following, and reduced motion skips it all.
Badges #
- Add
BottomBarBadge.dot(),.count()and.label()forBottomBarItem.badge. Badges scale in from the top-end corner with a slight overshoot and scale out before they go. Counts roll their digits, the width follows the text, a change mid-flight retargets smoothly, and reduced motion snaps. The Material 3 placement mirrors in RTL. SetBottomBarItemThemeData.badgeto aBottomBarBadgeThemeDatato style every badge. The item's accessible name now includes its badge, such as "Inbox, 3 new". Raw widgets inbadge:keep working as before.
Gestures #
- Add
BottomBarItems.onReselected, called when the selected item is tapped again or picked again by a drag.onSelectedstill fires after it. AddscrollToStartOnReselectto scroll the visible list back to its start on a reselect. AddBottomBarItemThemeData.hapticswithBottomBarHapticsto play a selection click or a light impact. AddBottomBarItem.onLongPressandBottomBarItems.onLongPressed. While one is set, the tooltip shows on hover only, and the item exposes a long-press action to assistive technology. AddBottomBarItems.dragToSelect. The indicator follows the finger, and a release selects the item under it with the finger's velocity. It is off in narrow rows and in rows without an indicator. It works in RTL, and reduced motion keeps the indicator still during the drag. There is no double-tap callback on purpose. All defaults keep today's behaviour.
Centre action #
- Add
BottomBarItems.centerAction, aBottomBarCenterActionbutton for the middle of a row. Its styles areinline(the default),raised, which sits partly above the bar's top edge, andnotched, which also cuts a smooth circular notch in the bar. The notch follows the action, and the bar's fill, border and shadow follow the notch. The action takes the middle slot and is not a tab. The raised part is tappable, counts inBottomBarScope.barHeightandBottomBarBodyPadding, and hides with the bar. A row too narrow for its items falls back to inline, and so does an action outside aBottomBar. It works in RTL, and reduced motion snaps the press. SetBottomBarItemThemeData.centerActionto style it. Rows without a centre action are unchanged.
Surface #
- Add
BottomBarSurfaceandBottomBarThemeData.surface.BottomBarSurface.glass()blurs and tints what scrolls under the bar, with an edge highlight and shadows..solid()is an opaque fill, and both lerp. The glass clips to the bar's outline, notch included, and hides with the bar. Shadows never darken a translucent fill. High contrast swaps the glass for an opaquefallbackColor. Bars without a surface paint as before. - Add
BottomBarThemeData.scrollEdgeSurface, like UIKit'sscrollEdgeAppearance. The bar paintssurfacewhile content scrolls under it and this surface at the edge: the end of the visible list, the start of areverse: truelist, or a list shorter than the viewport. It blends withBottomBarSurface.lerpon the bar's spring. Reduced motion snaps, high contrast paints the opaque fallback, and bars without it paint as before.
Recipes #
- Add a go_router
StatefulShellRouterecipe toEXAMPLES.mdand ago-router-shelldemo. Only the example app depends on go_router.
Fixes #
- Fix the hidden action doing nothing when the body has no scrollable to
scroll, such as a WebView driven by
reportScroll, or after the scrolled list was disposed by a body swap. Tapping it now always shows the bar. Fixes #7. - Fix the hidden action and
scrollToStart/scrollToEndscrolling a list that is no longer on screen, such as an inactiveIndexedStackchild or a disposed list. They now target the most recently scrolled list that is still attached and visible. - Drop the unused
cupertino_uidependency.
3.0.1 #
- Allow compatible 1.x releases of
material_uiandcupertino_ui, including their latest versions on Flutter 3.47, while retaining Flutter 3.44 support. - Fix
BottomBarItemgrowing to fill the screen height when used inside aBottomBar, which turnedBottomBarItemsbars into full-height cards. Items in an explicitly sizedBottomBarItemsrow still fill its height. - Fix
avoidKeyboardremounting the bar when the keyboard opened, which dropped focus from text fields inBottomBar.childand 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. ForBottomBarTransition.slide,slideStartis now measured from the edge the bar slides toward, so the defaultOffset(0, 2)always clears it.slideAndFadekeeps 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.0and 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 tomaterial_ui; migrated apps no longer needMaterialUiCompatibilityBridgefor this package. BottomBarLayoutandBottomBarLayout.adaptivenow defaultborderRadiusto 28. PassBorderRadius.zerofor a square bar.
Added #
BottomBarLayout.avoidKeyboard(defaulttrue): pads the bar and hidden action byMediaQuery.viewInsets.bottomso 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 affectBottomBarScope.barHeightorBottomBarBodyPadding.BottomBarController.reportScroll({required double delta}): drives the bar's threshold/reverse/hideOnScrollvisibility rules from a scroll source that never emitsScrollNotifications, such as an embedded WebView. Visibility-only — it does not affectscrollToStart()/scrollToEnd(), which still require a realScrollPosition.BottomBarLabelBehavior(alwaysShow,onlySelected,alwaysHide) andBottomBarItems.labelBehavior: controls when descendantBottomBarItemlabels render. Exposed toBottomBarItemvia the new publicBottomBarItemsScopeinherited widget; items outside aBottomBarItemsrow keep thealwaysShowdefault.BottomBarScrollBehavior.keepVisibleOnFocus(defaulttrue): skips scroll-driven hide while the floatingBottomBar.childholds 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,
BottomBarItemswraps every child inExpanded, 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. ABottomBarItem'sTextlabel (with non-nulldata) is truncated to a single line with an ellipsis;Text.richand other label widgets are unaffected. -
Migrated from
package:flutter/material.dartto the standalonematerial_uipackage. 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 needMaterialUiCompatibilityBridgeon account of this package — without it, the bar resolvedTheme.of(context).colorSchemeagainst 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_uirequires. -
Attaching a
BottomBarControllerto a second bar now throws aFlutterErrorin debug builds as well, instead of anAssertionError. -
BottomBarLayoutandBottomBarLayout.adaptivenow defaultborderRadiusto 28 so passinglayout:no longer squares the bar. PassBorderRadius.zeroto opt out.
Fixed #
- Hidden bar descendants are excluded from keyboard focus, so a
TextFieldin the floating child cannot be tab-focused while the bar is hidden.
2.1.0 #
Added #
BottomBarLayout.maxWidthandBottomBarLayout.adaptive(maxWidth: ...)for width-capped adaptive layouts, pluscopyWith(clearMaxWidth: true)for returning a derived layout to an uncapped width.BottomBarBodyPaddingas the built-in way to reserve the live floating-bar footprint insideBottomBar.body.BottomBarScrollBehavior.showAtStartandBottomBarScrollBehavior.showOnScrollEndfor settling-based visibility restoration.
Changed #
BottomBarScope.barHeightnow reflects the full rendered footprint reserved by the bar, including configured offset and bottom safe-area when enabled.BottomBarItemaccessible naming is now deterministic:semanticLabelwins, otherwisetooltip, 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.transitionBuilderusage 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 followsColorScheme.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.
BottomBarControllerownership is strict: double-attach fails in debug and release, and visibility updates are accepted only from the owning bar.BottomBarControllerboundary scrolling now documents and uses explicit start/end semantics independent ofscrollOpposite.
Fixed #
BottomBarController.scrollToStart()always targetsScrollPosition.minScrollExtent, andscrollToEnd()always targetsScrollPosition.maxScrollExtent.NestedScrollViewboundary scrolling now targets the correct coordinated controller so start/end actions reset both header and body as expected.- Large
iconOffsetvalues 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 aNestedScrollView— the collapsedSliverAppBar/FlexibleSpaceBarstayed collapsed and the list landed below its true top. ANestedScrollViewscrolls 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 enclosingNestedScrollViewand drives its shared scroll coordinator with a single call — animating the outer controller to the top (which pulls the inner body up with it) forscrollToStart, and the inner controller to the bottom (which collapses the header) forscrollToEnd. (#21)
2.0.1 #
- Fix: the back-to-top icon became unclickable when a large
iconOffsetwas set. The icon was painted at the offset position but itsSafeAreaancestor 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'sSafeAreaso 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.0because the package uses Motor-backed motion. BottomBar.bodyis nowWidgetinstead ofWidget Function(BuildContext, ScrollController). The bar listens toScrollNotificationfrom any descendant scrollable; you no longer wire a controller through the builder.- The
barColor,width,offset,borderRadius,barAlignment,fit,clip, andrespectSafeAreaparameters moved intoBottomBarLayout. - The
duration,curve,start, andendparameters moved intoBottomBarMotion.BottomBarMotion()now defaults to Cupertino spring motion; existingBottomBarMotion(duration: ..., curve: ...)calls remain curve-based.start/end(doubles) are nowslideStart/slideEnd(Offsets). - The
hideOnScroll,reverse,scrollOpposite, andscrollDeltaThresholdparameters moved intoBottomBarScrollBehavior.scrollDeltaThresholdis nowdeltaThreshold. - The
iconWidth,iconHeight,iconDecoration, andbarDecorationparameters moved toBottomBarThemeData(per-instance overrides remain via thetheme:argument). BottomBarScrollControllerProvideris replaced byBottomBarScope. ThescrollControllerfield is gone; new fields arebarHeightandisVisible.- The hardcoded
Colors.blackdefault is replaced with Material 3colorScheme.surfaceContainerfor the bar andcolorScheme.primaryfor 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(...), andBottomBarMotion.motor(...)constructors.BottomBarThemeDataThemeExtensionfor app-wide defaults.BottomBarTransitionenum (slide,fade,scale,slideAndFade) plusBottomBarMotion.transitionBuilder.BottomBarItemandBottomBarItemshelpers for the common nav-item case.BottomBarScope.barHeightexposes the live rendered bar height to descendants for content-padding purposes.BottomBarScope.isVisibleexposes live visibility without owning a controller.- Notification-based scroll detection works with
NestedScrollView,CustomScrollView, multipleTabBarViewchildren, and any user-suppliedScrollControllerwith no wiring. BottomBarScrollBehavior.predicatefor filtering unwanted notifications.BottomBarControllernow asserts on double-attach in debug.
Repository:
- Package source moved from
packages/flutter_floating_bottom_bar/to repo root. The example app moved toexample/. Thepackages/directory is removed.
1.4.0 #
- Upgrade project/tooling for Flutter
3.41.4development via FVM. - Update SDK constraints and refresh dependencies.
- Add
BottomBarControllerfor programmaticshow,hide,toggle,scrollToStart, andscrollToEnd. - Add
onVisibilityChangedcallback for visibility state transitions. - Add
scrollDeltaThresholdto reduce flicker from minor scroll movement. - Add
iconSemanticLabelandiconTooltipfor better accessibility. - Improve internal scroll/visibility handling and test coverage.
1.3.0 #
- Added
respectSafeAreaproperty to control whether theBottomBarshould respect the safe area. - Removed deprecated
alignmentproperty (usebarAlignmentinstead). - Fixed
ScrollControllerissues 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, andiconDecorationproperties. - Remove
bottomproperty. - Deprecate
alignmentin favor ofbarAlignment. - Update all code examples and fix errors.
1.1.0 #
- Add
clipproperty 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.
