Using `TabBar.tabAlignment` to customize the alignment of tabs in a `TabBar`.
Original behavior
The `TabBar.tabAlignment` property sets where a Material 3 `TabBar` places tabs. The `TabAlignment` enum has the following values:
New behavior
When you set `TabBar.isScrollable` and `ThemeData.useMaterial3` to `true`, the tabs in a scrollable `TabBar` defaults to `TabAlignment.startOffset`. This aligns the tabs to the start of the scrollable `TabBar` with an offset of `52.0` pixels. This changes the previous behavior. The tabs were aligned to the start of the scrollable `TabBar` when more tabs needed to display than the width allowed.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses TabBar.tabAlignment, TabBar, TabAlignment and related APIs.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Before and after (from the official guide)
| 1 | TabBar( | |
| 2 | isScrollable: true, | |
| 3 | tabs: List<Tab>.generate( | |
| 4 | count, | |
| 5 | (int index) => Tab(text: 'Tab $index'), | |
| 6 | ).toList(), | |
| 7 | ); |
| 1 | TabBar( | |
| 2 | + | tabAlignment: TabAlignment.start, |
| 3 | isScrollable: true, | |
| 4 | tabs: List<Tab>.generate( | |
| 5 | count, | |
| 6 | (int index) => Tab(text: 'Tab $index'), | |
| 7 | ).toList(), | |
| 8 | ); |
Raw before / after
TabBar(
isScrollable: true,
tabs: List<Tab>.generate(
count,
(int index) => Tab(text: 'Tab $index'),
).toList(),
);TabBar(
tabAlignment: TabAlignment.start,
isScrollable: true,
tabs: List<Tab>.generate(
count,
(int index) => Tab(text: 'Tab $index'),
).toList(),
);Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
A Material 3 scrollable TabBar uses TabAlignment.startOffset as
the default tab alignment.
This aligns the tabs to the start of the
scrollable TabBar with an offset of 52.0 pixels.
To align the tabs to the start of the
scrollable TabBar, set TabBar.tabAlignment to TabAlignment.start.
This change also removed the 52.0 pixel offset.
The following code snippets show how to use TabBar.tabAlignment to
align tabs to the start of the scrollable TabBar:
Code before migration:
TabBar(
isScrollable: true,
tabs: List<Tab>.generate(
count,
(int index) => Tab(text: 'Tab $index'),
).toList(),
);Code after migration:
TabBar(
tabAlignment: TabAlignment.start,
isScrollable: true,
tabs: List<Tab>.generate(
count,
(int index) => Tab(text: 'Tab $index'),
).toList(),
);AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.