패키지, 저장소 및 앱 카테고리 검색

flutter_floating_bottom_bar 표지
패키지 상세v3.1.0

flutter_floating_bottom_bar

탭 바, 하단 탐색 바 등으로 사용할 수 있는 부유형 위젯을 표시할 수 있는 플러터 패키지입니다. 스크롤 이벤트에도 반응합니다.

AndroidiOSWebmacOSWindowsLinux
30일 다운로드
1.8만
좋아요
371
Pub 점수
160

패키지 설치

flutter pub add flutter_floating_bottom_bar

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

탭 바 또는 하단 탐색 바로 사용하기에 적합한 플로팅 하단 바 위젯을 제공하는 Flutter 패키지입니다. 스크롤 이벤트에 동적으로 반응하여 사용자의 스크롤 행동에 따라 자동으로 숨기거나 표시됩니다. Android, iOS, Web, macOS, Windows, Linux를 모두 지원하며, 다양한 플랫폼 간 원활한 통합을 위해 설계되었습니다. 콘텐츠를 가리지 않으면서도 탐색을 쉽게 접근할 수 있도록 하여 사용자 경험을 향상시킵니다. 가볍고 사용자 정의가 가능해 직관적인 하단 탐색과 반응형 동작이 필요한 앱에 적합합니다.

사용 사례

  • 스크롤 가능한 목록에서 하단 탐색
  • 모바일 앱에서의 플로팅 탭 바
  • 웹 애플리케이션에서 반응형 탐색
  • 크로스 플랫폼 앱에서의 동적 UI 요소
  • 콘텐츠가 많은 인터페이스에서의 사용자 경험 향상

주요 기능

  • 스크롤 인식 숨기기/보이기
  • 크로스 플랫폼 호환성
  • 사용자 정의 가능한 외관
  • 기존 위젯과의 간편한 통합
  • 다수의 플랫폼을 지원합니다

적합한 대상

  • 모바일 앱 개발자
  • 웹 애플리케이션 디자이너
  • 크로스 플랫폼 Flutter 프로젝트
  • UI/UX 중심 개발
  • 넓은 스크롤 가능한 콘텐츠를 가진 앱

고려 사항

  • 복잡한 레이아웃을 위해 추가 스타일링이 필요할 수 있습니다
  • 매우 긴 목록에 대한 성능 영향
  • 고급 애니메이션을 위한 제한된 사용자 정의
  • 정적 탐색 막대에 적합하지 않습니다
  • 중첩 스크롤 뷰에서 신중한 조작이 필요합니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

Floating Bottom Bar

A Flutter package that floats any widget above your content and reacts to scrolling. Use it as a tab bar, bottom navigation bar, search bar, command surface, or any custom child.

Platform Pub Package License: MIT Donate

Issues dock AI prompt dock Basic TabBar
Issues dock AI prompt dock Basic TabBar
Minimal API Nested scroll Badged nav
Minimal API Nested scroll Badged nav
Custom transition
Custom transition

Why this package

  • Host any widget as the floating bar: TabBar, BottomBarItems, a search composer, or a custom Row.
  • Scroll detection is notification-based. Most setups need no ScrollController plumbing.
  • BottomBarLayout.adaptive(maxWidth: ...) fills the host width while keeping a hard cap for tablets, desktop, and wide layouts.
  • BottomBarBodyPadding reserves the bar's full measured footprint, including configured offset and bottom safe-area, so body content stays clear even while the bar is hidden.
  • BottomBarMotion() defaults to Motor-backed Cupertino spring motion with velocity-preserving redirects when scroll direction changes mid-animation.
  • Custom transitions are supported, but they must stay paint-only and preserve the child's layout footprint.
  • The hidden action is accessibility-safe by default: it is non-interactive and excluded from semantics while the bar is visible, keeps at least a 48x48 hit target when active, uses direction-aware icon/tooltip text, and defaults its glyph color to ColorScheme.onPrimary.
  • Reduced-motion environments snap directly to the final shown/hidden state.
  • BottomBarController supports imperative show/hide plus scrollToStart()/scrollToEnd(), including correct NestedScrollView boundary targeting.
  • Motion from the motor package is re-exported intentionally for BottomBarMotion.motor(...).

Install

Requires Dart >=3.12.0 and Flutter >=3.44.0.

See the 3.0.0 release notes for the complete list of new layout, scrolling, accessibility, and reliability improvements.

flutter pub add flutter_floating_bottom_bar
import 'package:flutter_floating_bottom_bar/flutter_floating_bottom_bar.dart';

Claude Code skill

If you use Claude Code, this repo ships a skill for integration, migration, and debugging help around this package.

Install by copying .claude/skills/flutter-floating-bottom-bar/ into your Claude skills directory.

Basic usage

BottomBar(
  layout: const BottomBarLayout.adaptive(maxWidth: 420),
  body: BottomBarBodyPadding(
    padding: const EdgeInsets.only(top: 24),
    child: ListView.builder(
      padding: const EdgeInsets.symmetric(horizontal: 16),
      itemCount: 50,
      itemBuilder: (_, index) => ListTile(title: Text('Item $index')),
    ),
  ),
  child: const Padding(
    padding: EdgeInsets.symmetric(horizontal: 16, vertical: 14),
    child: Row(
      mainAxisAlignment: MainAxisAlignment.spaceBetween,
      children: [
        Icon(Icons.home_rounded),
        Text('Floating bar'),
        Icon(Icons.search_rounded),
      ],
    ),
  ),
)

BottomBar needs two required arguments:

  • body: the subtree that emits ScrollNotifications.
  • child: the floating widget shown above that body.

The bar is stacked above the body, so use BottomBarBodyPadding when your body should reserve enough bottom space to stay clear of the bar.

Common recipes

Adaptive width + stable body padding

Use BottomBarLayout.adaptive(maxWidth: ...) to span narrow screens while stopping at a defined maximum on wide screens. Pair it with BottomBarBodyPadding when the body should reserve the full footprint.

BottomBar(
  layout: const BottomBarLayout.adaptive(maxWidth: 440),
  body: const BottomBarBodyPadding(
    child: CustomScrollView(
      slivers: [
        SliverAppBar(title: Text('Inbox')),
        SliverList.list(
          children: [
            ListTile(title: Text('Message 1')),
            ListTile(title: Text('Message 2')),
          ],
        ),
      ],
    ),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Compose')),
  ),
)

BottomBarScope.barHeight and BottomBarBodyPadding use the bar's measured layout footprint, not its animated transform. The reported value includes the bar height plus configured layout.offset and bottom safe-area when respectSafeArea is enabled.

Nested scroll views

BottomBarController.scrollToStart() always targets the minimum extent and scrollToEnd() always targets the maximum extent. In a NestedScrollView, the controller automatically chooses the correct coordinated boundary controller:

  • scrollToStart() drives the outer controller so pinned/expanded header slivers return to their true top state.
  • scrollToEnd() drives the inner controller so the body scrolls to the end and the header collapses naturally.

If your body emits unrelated notifications, use BottomBarScrollBehavior.predicate to filter them.

BottomBar(
  controller: controller,
  scrollBehavior: BottomBarScrollBehavior(
    predicate: (notification) => notification.depth == 0,
    showAtStart: true,
    showOnScrollEnd: true,
  ),
  body: NestedScrollView(
    headerSliverBuilder: (_, __) => const [
      SliverAppBar(
        pinned: true,
        expandedHeight: 180,
        flexibleSpace: FlexibleSpaceBar(title: Text('Nested scroll')),
      ),
    ],
    body: ListView.builder(
      itemCount: 100,
      itemBuilder: (_, index) => ListTile(title: Text('Row $index')),
    ),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Scroll-aware')),
  ),
)
Non-notification scroll sources (e.g. WebView)

BottomBar normally drives visibility from ScrollNotifications bubbled up from body. Some content — most notably an embedded WebView — scrolls internally without ever emitting one. For those cases, call BottomBarController.reportScroll from the WebView's own scroll callback:

controller.reportScroll(delta: newPixels - oldPixels);

This drives the same threshold/reverse/hideOnScroll visibility rules as body scrolling. It only affects visibility — scrollToStart()/scrollToEnd() still require a real ScrollPosition, which a WebView cannot provide.

Custom transitions

Custom transition builders must preserve the child's layout footprint. Use paint-only wrappers such as Opacity, Transform.translate, or Transform.scale.

Do not use layout-changing widgets such as SizeTransition or Align with a heightFactor; those break the stable footprint contract used by BottomBarScope.barHeight and BottomBarBodyPadding.

BottomBar(
  motion: BottomBarMotion(
    transitionBuilder: (context, animation, child) {
      final value = animation.value.clamp(0.0, 1.0);
      return Opacity(
        opacity: value,
        child: Transform.scale(
          scale: 0.92 + (0.08 * value),
          child: child,
        ),
      );
    },
  ),
  body: ListView.builder(
    itemCount: 100,
    itemBuilder: (_, index) => ListTile(title: Text('Row $index')),
  ),
  child: const SizedBox(
    height: 56,
    child: Center(child: Text('Paint-only transition')),
  ),
)

Spring progress can overshoot. Clamp animation.value before using it for opacity or scale.

BottomBarItems and BottomBarItem

BottomBarItems is a row helper. BottomBarItem is an opinionated item widget with built-in accessibility and RTL-aware badge placement.

  • The badge uses PositionedDirectional, so it follows the top-end corner in both LTR and RTL layouts.
  • The item exposes button semantics, selection state, and enabled state.
  • The tappable surface keeps at least a 48x48 target.
  • Accessible naming is deterministic: semanticLabel wins, otherwise tooltip, otherwise descendant semantics.
  • When semanticLabel or tooltip provides the explicit accessible name, descendant semantics are excluded to avoid duplicate announcements.
  • 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 left untouched.
  • BottomBarItems.labelBehavior (BottomBarLabelBehavior.alwaysShow by default) controls when descendant labels render: alwaysShow, onlySelected, or alwaysHide. An item used outside a BottomBarItems row always shows its label.

Migration from v1.x

v1.x v2.x Migration
body: (context, controller) => Widget body: Widget Drop the builder. The bar listens to ScrollNotifications from descendant scrollables.
barColor removed Use BottomBarThemeData.barDecoration or theme:.
width, offset, borderRadius, barAlignment, fit, clip, respectSafeArea BottomBarLayout Move these into layout: BottomBarLayout(...). barAlignment became alignment.
duration, curve, start, end BottomBarMotion BottomBarMotion() now defaults to Cupertino spring motion. start/end became slideStart/slideEnd.
hideOnScroll, reverse, scrollOpposite, scrollDeltaThreshold BottomBarScrollBehavior Move these into scrollBehavior: BottomBarScrollBehavior(...). scrollDeltaThreshold became deltaThreshold.
iconWidth, iconHeight, iconDecoration, barDecoration BottomBarThemeData Move these to the theme or the theme: override.
BottomBarScrollControllerProvider BottomBarScope The old controller provider was replaced by BottomBarScope, which exposes barHeight and isVisible.

No backward-compatibility shim ships with v2.

API quick reference

BottomBar
Parameter Type Default Notes
child Widget required Floating content shown above the body.
body Widget required Descendant scrollables here drive hide/show via notifications.
controller BottomBarController? null Imperative show/hide/scroll API.
layout BottomBarLayout? null Falls back to theme layout, then const BottomBarLayout().
motion BottomBarMotion? null Falls back to theme motion, then const BottomBarMotion().
scrollBehavior BottomBarScrollBehavior? null Falls back to theme scroll behavior, then const BottomBarScrollBehavior().
theme BottomBarThemeData? null Per-instance theme overrides.
icon BackToTopIconBuilder? null Custom hidden action visual.
showIcon bool true Enables or removes the built-in hidden action.
iconSemanticLabel String? null Defaults to the direction-aware tooltip text.
iconTooltip String? null Defaults to Scroll to top or Scroll to bottom.

The hidden action is only interactive while the bar is hidden. While the bar is visible it is ignored for hit testing and removed from the semantics tree.

BottomBarLayout
Field Type Default Notes
width double 300 Requested bar width before viewport/max-width clamping.
maxWidth double? null Optional explicit width cap after host constraints.
offset double 10 Outer padding applied around the bar or hidden action.
borderRadius BorderRadius BorderRadius.circular(28) Matches the default Material 3 bar decoration; pass BorderRadius.zero for a square bar.
iconOffset Offset Offset.zero Extra translation applied only to the hidden action.
alignment Alignment Alignment.bottomCenter Shared alignment for the bar and hidden action.
fit StackFit StackFit.loose Host stack fit.
clip Clip Clip.hardEdge Host stack clip behavior.
respectSafeArea bool true Wraps the bar and hidden action in SafeArea.
avoidKeyboard bool true Pads the bar and hidden action by MediaQuery.viewInsets.bottom so they sit above the keyboard. No-op when insets are 0 (typical inside a Scaffold body).

Use BottomBarLayout.adaptive(maxWidth: ...) to fill available width up to a hard cap. When deriving layouts, copyWith(clearMaxWidth: true) explicitly removes an existing cap.

BottomBarMotion
Field Type Default Notes
mode BottomBarMotionMode cupertino BottomBarMotion() defaults to Cupertino spring mode.
duration Duration 500ms in default Cupertino mode Used for curved motion and scroll-to-boundary animation timing.
curve Curve Curves.easeOutCubic Used by curved motion and controller boundary scrolling.
cupertinoPreset BottomBarCupertinoMotion snappy Default Cupertino preset.
transition BottomBarTransition slide Built-in transition when transitionBuilder is null.
transitionBuilder Widget Function(BuildContext, Animation<double>, Widget)? null Overrides the enum. Must preserve layout footprint and stay paint-only.
slideStart Offset Offset(0, 2) Hidden offset for slide and slideAndFade.
slideEnd Offset Offset.zero Visible offset for slide and slideAndFade.

Reduced-motion environments snap to the target shown/hidden state instead of animating.

BottomBarScrollBehavior
Field Type Default Notes
hideOnScroll bool true Disables scroll-driven hiding when false.
reverse bool false Inverts the scroll direction that hides vs shows the bar.
scrollOpposite bool false Changes only the built-in hidden action direction, tooltip, and glyph. It does not change scrollToStart() or scrollToEnd().
deltaThreshold double 8 Minimum absolute delta required before visibility can flip.
showAtStart bool false Forces the bar visible when a scrollable reaches its minimum extent.
showOnScrollEnd bool false Forces the bar visible when scrolling settles.
keepVisibleOnFocus bool true Skip scroll-hide while the floating child has focus. BottomBarController.hide() still hides it.
predicate bool Function(ScrollNotification)? null Skip notifications entirely when it returns false.
BottomBarController
Member Notes
isVisible Tracks the currently attached bar's visibility.
isAttached Whether the controller is attached to a live bar.
show() / hide() / toggle() Imperative visibility controls.
scrollToStart() Always scrolls the last active scrollable to its minimum extent.
scrollToEnd() Always scrolls the last active scrollable to its maximum extent.
reportScroll(delta: ...) Drives visibility from a source that doesn't emit ScrollNotifications (e.g. WebView). Visibility only; doesn't affect scrollToStart/scrollToEnd.

A controller can own only one live bar at a time. Double-attach fails in both debug and release, and visibility updates are accepted only from the owning bar binding.

BottomBarScope

BottomBarScope exposes two listenables inside BottomBar.body:

  • barHeight: the live measured bar footprint, including offset and bottom safe-area when enabled.
  • isVisible: the current shown/hidden target state.

Use BottomBarBodyPadding when you want the common "reserve the bottom footprint for me" behavior without wiring your own ValueListenableBuilder.

Examples and demos

  • API recipes: EXAMPLES.md
  • Runnable demo app: example/
  • Demo entry point: example/lib/main.dart

Contributing

See CONTRIBUTING.md for setup, quality checks, and release dry-run steps.

Bugs or requests

Open an issue at https://github.com/codenameakshay/flutter-floating-bottom-bar/issues.

카테고리

의존성

의존성 목록 2 개

소스 저장소

이 패키지를 사용하는 프로젝트