Flutter AppBar: SliverAppBar, Custom Patterns, and M3 Migration

The Flutter AppBar widget sits at the top of almost every Scaffold in production. Despite being a single widget declaration, it controls six distinct layout zones, interacts with the system status bar, and changed default behavior meaningfully when Material 3 became the default theme in Flutter 3.16. Tutorials written before that release are quietly wrong in at least two ways: centerTitle now defaults to true on all platforms in M3 (previously it was platform-dependent), and the elevation drop shadow is replaced by scrolledUnderElevation with a surface tint.

Our team maintains the GetWidget open-source Flutter UI kit (4,811 stars, 23K monthly pub.dev downloads) and ships Flutter across 10 industries. AppBar decisions come up in every project. We also recently published a full guide on flutter tabbar and navigation widgets that pairs with this one. TabBar almost always lives inside an AppBar's bottom slot, so reading both together gives you the full navigation picture.

This guide covers the AppBar anatomy, theming with AppBarTheme, SliverAppBar collapse modes, PreferredSize custom app bars, the FlexibleSpaceBar collapsing pattern, AppBar plus TabBar pairing, accessibility requirements, the most common M3 migration bugs, and a decision matrix for when to use each variant.

Flutter AppBar anatomy: leading, title, actions, bottom, and flexibleSpace

AppBar is not a single slot widget. It divides its space across six named zones, and understanding which zone controls what prevents the layout confusion that shows up in every AppBar-related Stack Overflow thread.

The leading slot occupies the left side of the toolbar row. Flutter fills it automatically with a back button (when Navigator has a previous route) or a drawer hamburger (when Scaffold.drawer is set). You can override it with any widget. Setting automaticallyImplyLeading to false suppresses the automatic leading widget entirely.

The title occupies the center of the toolbar row by default in M3, or the left (after the leading widget) in M2. In M3, centerTitle defaults to true on all platforms. In M2 it defaulted to true on iOS and false on Android. This single behavioral difference is responsible for a large share of M3 migration visual regressions.

The actions list sits on the right side of the toolbar. Each item is usually an IconButton. When more actions than fit are needed, Flutter conventionally uses a PopupMenuButton as the last action to provide an overflow menu. There is no automatic overflow: if you add eight icons to actions, they clip.

The bottom slot sits below the toolbar row and adds height to the AppBar. Its canonical use is TabBar (which we cover in the pairing section below). It accepts any PreferredSizeWidget, so you can place a search bar, a progress indicator, or a custom widget row there. The bottom slot height is included in AppBar.preferredSize, which affects Scaffold's safe area calculations.

The flexibleSpace slot renders behind the toolbar row and the bottom slot. It fills the entire AppBar height. In a standard AppBar it is used for background gradients or images. In SliverAppBar it becomes the expanded content that collapses as the user scrolls. The flexibleSpace widget does not receive padding automatically, so you manage top padding for the status bar manually if needed.

Basic flutter app bar with actions: the production starting point

The minimal AppBar that covers 80% of production screens: a back button (automatic from Navigator), a title, and one to three flutter appbar actions on the right. We start every project with this structure and only add complexity where the design actually requires it.

Scaffold(
  appBar: AppBar(
    title: const Text('Orders'),
    // centerTitle defaults to true in M3; set false to left-align
    centerTitle: false,
    actions: [
      IconButton(
        icon: const Icon(Icons.search),
        tooltip: 'Search orders',
        onPressed: () => _openSearch(context),
      ),
      IconButton(
        icon: const Icon(Icons.filter_list),
        tooltip: 'Filter',
        onPressed: () => _openFilter(context),
      ),
      PopupMenuButton<String>(
        onSelected: _handleMenuAction,
        itemBuilder: (context) => [
          const PopupMenuItem(value: 'export', child: Text('Export CSV')),
          const PopupMenuItem(value: 'settings', child: Text('Settings')),
        ],
      ),
    ],
  ),
  body: const OrdersList(),
);

The leading widget in this example is automatic: Navigator detects the previous route and inserts a BackButton. If you are on a root screen with Scaffold.drawer, Flutter inserts a DrawerButton instead. Both are accessible by default; the DrawerButton has the Semantics label "Open navigation menu" built in.

Theming the flutter appbar widget with AppBarTheme and M3 changes

Setting colors per-AppBar instance does not scale. The correct approach is AppBarTheme inside your ThemeData, which applies to every AppBar in the app without per-widget overrides. In M3 the relevant properties changed significantly compared to M2.

ThemeData(
  useMaterial3: true,
  colorScheme: ColorScheme.fromSeed(
    seedColor: const Color(0xFF1A56DB),
  ),
  appBarTheme: const AppBarTheme(
    // M3: backgroundColor defaults to colorScheme.surface
    // Override only if your brand requires a non-surface color
    backgroundColor: Colors.transparent,
    // M3: foregroundColor controls title + icon color
    foregroundColor: Color(0xFF1A1A1A),
    // elevation: 0 is the M3 default — shadow is gone
    elevation: 0,
    // scrolledUnderElevation adds a surface tint when content
    // scrolls under the AppBar. Set to 0 to suppress it.
    scrolledUnderElevation: 3,
    // centerTitle: true is the M3 default
    centerTitle: false, // override to match your design system
    titleTextStyle: TextStyle(
      fontSize: 20,
      fontWeight: FontWeight.w600,
      letterSpacing: -0.3,
    ),
    iconTheme: IconThemeData(size: 24),
    actionsIconTheme: IconThemeData(size: 24),
  ),
);

The M3 surface tint on scroll is intentional. It signals to the user that the AppBar is elevated above scrolling content. If your brand uses a colored AppBar (not the default surface color), the tint may conflict with your brand color. In that case set surfaceTintColor: Colors.transparent in AppBarTheme to suppress it while keeping M3 semantics everywhere else.

Flutter SliverAppBar: pinned, floating, snap, and expandedHeight

A flutter sliver appbar is AppBar's scroll-aware cousin. It lives inside a CustomScrollView's slivers list and participates in the sliver scroll protocol, meaning it can expand, collapse, pin, and float in response to the user's scroll position. A regular AppBar cannot do any of this.

Three boolean properties control flutter SliverAppBar scroll behavior. pinned: true keeps the collapsed toolbar visible when the user scrolls past the expanded area. floating: true makes the collapsed bar reappear immediately when the user starts scrolling up, even if they have not reached the top. snap: true (requires floating: true) makes the bar snap fully open or closed on a partial upward scroll gesture, never stopping halfway.

CustomScrollView(
  slivers: [
    SliverAppBar(
      expandedHeight: 220,
      pinned: true,      // toolbar stays visible when collapsed
      floating: false,   // set true for on-scroll-up reveal
      snap: false,       // requires floating: true
      flexibleSpace: FlexibleSpaceBar(
        title: const Text('Catalog'),
        centerTitle: true,
        // background fills the expanded area
        background: Image.asset(
          'assets/catalog_hero.jpg',
          fit: BoxFit.cover,
        ),
        // collapseMode controls how background fades/parallaxes
        collapseMode: CollapseMode.parallax,
        stretchModes: [StretchMode.zoomBackground],
      ),
      // actions visible in both expanded and collapsed states
      actions: [
        IconButton(
          icon: const Icon(Icons.search),
          tooltip: 'Search catalog',
          onPressed: () {},
        ),
      ],
    ),
    SliverList(
      delegate: SliverChildBuilderDelegate(
        (context, index) => ListTile(title: Text('Item $index')),
        childCount: 100,
      ),
    ),
  ],
);

expandedHeight sets the total height of the SliverAppBar when fully expanded. The collapsed height defaults to kToolbarHeight (56dp). The difference between expanded and collapsed height is the space the flexibleSpace occupies and releases as the user scrolls. Set expandedHeight to at least kToolbarHeight plus the content you want to show in the expanded state.

Custom flutter appbar with PreferredSize

Scaffold.appBar does not accept an arbitrary widget. It requires a PreferredSizeWidget, which is an interface that exposes a preferredSize getter returning a Size. AppBar implements this interface. When you want a flutter custom appbar that does not use AppBar's internal layout, wrap your custom widget in a PreferredSize.

class BrandAppBar extends StatelessWidget implements PreferredSizeWidget {
  final String title;
  final List<Widget> actions;

  const BrandAppBar({
    super.key,
    required this.title,
    this.actions = const [],
  });

  @override
  Size get preferredSize => const Size.fromHeight(64);

  @override
  Widget build(BuildContext context) {
    return Container(
      height: preferredSize.height,
      decoration: BoxDecoration(
        color: Theme.of(context).colorScheme.surface,
        border: Border(
          bottom: BorderSide(
            color: Theme.of(context).dividerColor,
            width: 1,
          ),
        ),
      ),
      padding: EdgeInsets.only(
        top: MediaQuery.of(context).padding.top, // status bar
      ),
      child: Row(
        children: [
          const SizedBox(width: 16),
          Text(
            title,
            style: Theme.of(context).textTheme.titleLarge,
          ),
          const Spacer(),
          ...actions,
          const SizedBox(width: 8),
        ],
      ),
    );
  }
}

// Usage
Scaffold(
  appBar: BrandAppBar(
    title: 'Dashboard',
    actions: [
      IconButton(
        icon: const Icon(Icons.notifications_outlined),
        tooltip: 'Notifications',
        onPressed: () {},
      ),
    ],
  ),
  body: const DashboardBody(),
);

The critical detail in a PreferredSize custom AppBar is accounting for the status bar height. In the example above we read MediaQuery.of(context).padding.top and add it as top padding. Without this, your custom bar content renders behind the status bar on devices without a notch and on top of notch content on devices that have one. AppBar handles this automatically; custom PreferredSize widgets do not.

Collapsing AppBar with FlexibleSpaceBar

FlexibleSpaceBar is the widget that makes SliverAppBar useful. It manages the visual transition between the expanded and collapsed states: the title scales down and moves from the expanded area into the toolbar position, the background fades or parallaxes, and optional stretch modes activate when the user overscrolls beyond the top.

The collapseMode property controls how the background behaves as the app bar collapses. CollapseMode.parallax moves the background at a slower rate than the scroll, creating a depth effect. CollapseMode.pin keeps the background stationary while the overlay shrinks. CollapseMode.none scrolls the background out with the expanded area.

SliverAppBar(
  expandedHeight: 280,
  pinned: true,
  stretch: true, // enables overscroll stretch
  flexibleSpace: FlexibleSpaceBar(
    title: const Text(
      'Product Detail',
      style: TextStyle(fontSize: 16),
    ),
    centerTitle: false,
    titlePadding: const EdgeInsets.only(left: 16, bottom: 14),
    background: Stack(
      fit: StackFit.expand,
      children: [
        Image.network(
          'https://example.com/product.jpg',
          fit: BoxFit.cover,
        ),
        // scrim so white title stays readable over any image
        const DecoratedBox(
          decoration: BoxDecoration(
            gradient: LinearGradient(
              begin: Alignment.topCenter,
              end: Alignment.bottomCenter,
              colors: [Colors.transparent, Colors.black54],
            ),
          ),
        ),
      ],
    ),
    collapseMode: CollapseMode.parallax,
    stretchModes: [
      StretchMode.zoomBackground,
      StretchMode.blurBackground,
    ],
  ),
);

The gradient scrim in the example above is something our team adds to every collapsing AppBar with a photo background. Without it, the white title text becomes unreadable over light-colored image regions. The gradient is cheap to render and eliminates a whole class of accessibility contrast failures without custom title color logic.

AppBar plus TabBar: using the bottom slot for flutter appbar actions and tabs

Placing TabBar in AppBar's bottom slot is the standard pattern for content-category screens: orders/returns/history, inbox/sent/archived, or any other named section grouping. The bottom slot accepts any PreferredSizeWidget, and TabBar implements that interface.

DefaultTabController(
  length: 3,
  child: Scaffold(
    appBar: AppBar(
      title: const Text('Messages'),
      // flutter appbar actions: visible alongside the tab row
      actions: [
        IconButton(
          icon: const Icon(Icons.compose),
          tooltip: 'Compose new message',
          onPressed: () {},
        ),
      ],
      bottom: TabBar(
        // In M3, TabBar uses primary color for indicator by default.
        // Override with TabBarTheme or per-instance properties.
        indicatorColor: Theme.of(context).colorScheme.primary,
        labelColor: Theme.of(context).colorScheme.primary,
        unselectedLabelColor:
            Theme.of(context).colorScheme.onSurfaceVariant,
        tabs: const [
          Tab(text: 'Inbox'),
          Tab(text: 'Sent'),
          Tab(text: 'Archived'),
        ],
      ),
    ),
    body: const TabBarView(
      children: [
        InboxTab(),
        SentTab(),
        ArchivedTab(),
      ],
    ),
  ),
);

The AppBar height with a TabBar in the bottom slot is kToolbarHeight (56dp) plus TabBar's preferredSize height (48dp by default), totaling 104dp. This matters when you calculate scroll offsets or position overlays relative to the AppBar. For deeply nested content patterns that require expandable sections inside tabs, pairing this with a flutter accordion widget is a common approach we use for complex content hierarchies.

When you want the AppBar to scroll away with content but the TabBar to remain pinned, the correct setup is SliverAppBar (with pinned: false) containing the title and a SliverPersistentHeader (or a second SliverAppBar with pinned: true) for the TabBar. Placing TabBar directly in SliverAppBar's bottom slot makes it collapse with the AppBar, which is usually not what you want for a tab navigation pattern.

Accessibility: Semantics for back button and flutter appbar actions

AppBar's automatic back button uses the Semantics label "Back" by default, which satisfies the minimum accessibility requirement for screen readers. If your app has a custom leading widget that performs navigation, you must add Semantics manually. The framework does not infer the purpose of a custom GestureDetector or InkWell.

AppBar(
  leading: Semantics(
    label: 'Back to product list',
    button: true,
    child: IconButton(
      icon: const Icon(Icons.arrow_back_ios_new),
      // tooltip also sets Semantics label; both are fine to set
      tooltip: 'Back',
      onPressed: () => Navigator.of(context).pop(),
    ),
  ),
  title: const Text('Product Detail'),
  actions: [
    // IconButton tooltip IS the accessible label for screen readers
    IconButton(
      icon: const Icon(Icons.share),
      tooltip: 'Share product', // required for a11y
      onPressed: _shareProduct,
    ),
    IconButton(
      icon: const Icon(Icons.favorite_border),
      tooltip: 'Add to favourites', // required for a11y
      onPressed: _toggleFavourite,
    ),
  ],
);

Title accessibility in AppBar deserves attention too. AppBar wraps its title in a Semantics node with header: true by default when the title is in the toolbar row. Screen readers announce it as a heading, which gives users a landmark to navigate to. If you replace the title widget with a fully custom widget (a search field, for example), you may need to add Semantics(header: true) manually to preserve that announcement behavior.

Common flutter appbar bugs: M3 elevation, centerTitle platform diff, action overflow

Three bugs appear in almost every codebase we review that has migrated from M2 to M3 or was written by developers using M2 tutorials.

Bug one: elevation set but shadow not visible. A developer sets elevation: 4 on AppBar expecting a drop shadow, but the shadow does not appear. Cause: useMaterial3: true disables the drop shadow by design. Fix: use shadowColor to re-enable the shadow in M3, or accept the M3 convention and use scrolledUnderElevation with a surface tint instead.

Bug two: title left-aligned on iOS, centered on Android (or vice versa). In M2 this was platform-controlled. In M3 the default is always centered. If your design requires left-aligned titles, set centerTitle: false explicitly in AppBarTheme. Relying on platform defaults across M2 and M3 produces inconsistent layouts on different test devices.

Bug three: action icons overflow or clip with many actions. AppBar does not automatically overflow actions into a menu. If five icons are passed to actions, all five render. On smaller screen widths they push the title text into a single character or clip entirely. The fix is to always include a PopupMenuButton as the last action item and move secondary actions into it. We limit visible actions to three icons maximum in our design system.

// Re-enable drop shadow in M3 (M2 behavior)
AppBar(
  elevation: 4,
  shadowColor: Colors.black,       // required in M3 to show shadow
  surfaceTintColor: Colors.transparent, // suppress the M3 tint
  title: const Text('Settings'),
);

// OR: embrace M3 semantics — shadow on scroll only
AppBar(
  scrolledUnderElevation: 4,       // shadow appears when content scrolls under
  shadowColor: Colors.black,
  title: const Text('Settings'),
);

Decision matrix: AppBar vs SliverAppBar vs custom flutter app bar

Choosing the wrong AppBar variant costs a rebuild. AppBar is for standard screens with a fixed header. SliverAppBar is for scroll-driven expansion and collapse. Custom PreferredSize is for design systems that cannot use either. The matrix below maps the decision.

GetWidget GFAppBar and header components

Our open-source GetWidget Flutter UI kit ships GFAppBar as a wrapper around Flutter's AppBar that adds pre-built search mode toggling, gradient support, and a leading-widget API consistent with the rest of the GF design system. If your project already uses GetWidget components, GFAppBar reduces the overhead of wiring up a search-mode AppBar (the expand-to-search-field pattern) from custom state management to a single searchBar parameter.

import 'package:getwidget/getwidget.dart';

GFAppBar(
  title: const Text('GetWidget Store'),
  // GFAppBar adds searchBar toggle built-in
  searchBar: true,
  searchHintText: 'Search products...',
  // gradient background via GFGradient
  flexibleSpace: Container(
    decoration: const BoxDecoration(
      gradient: LinearGradient(
        colors: [Color(0xFF1A56DB), Color(0xFF3B82F6)],
        begin: Alignment.topLeft,
        end: Alignment.bottomRight,
      ),
    ),
  ),
  actions: [
    GFIconButton(
      icon: const Icon(Icons.shopping_cart_outlined),
      type: GFButtonType.transparent,
      onPressed: () {},
    ),
  ],
);

GFAppBar passes through all standard AppBar properties. If a parameter GFAppBar does not expose is needed (for example, scrolledUnderElevation), you can access the underlying AppBar via Flutter's theme system or use a standard AppBar instead. We do not add GetWidget component complexity where Flutter's built-in widget already covers the requirement cleanly.

The GetWidget UI kit is available on pub.dev (23K monthly downloads, 4,811 GitHub stars) and is MIT-licensed. The full component set covers 1,000+ widgets across buttons, cards, avatars, tabs, sliders, and navigation patterns. For teams starting from scratch on a design system, it provides a consistent baseline that significantly reduces per-component styling work.

FAQ: flutter appbar widget questions from production

AppBar choices shape the first 64 pixels every user sees. Getting the theming right at the AppBarTheme level saves repeated per-widget overrides across every screen. Getting the SliverAppBar configuration right before building scroll-driven layouts saves a full architecture swap later. The M3 behavioral changes (centerTitle, scrolledUnderElevation, surface tint) are the most common source of visual regressions in apps migrated from M2, and all of them are straightforward to address once you know the property mapping.

Our team ships Flutter navigation architecture across healthcare, fintech, and ecommerce apps. AppBar is the entry point for navigation, accessibility, and visual identity. The patterns above represent what we actually use in production, not documentation examples. The specifics vary by project, but the underlying widget selection logic holds across all of them.