Flutter Dynamic TabController with TickerProviderStateMixin

Problem

When building a TabBar with dynamic tabs (tabs that show/hide based on feature availability, user preferences, or async state), recreating the TabController during the widget lifecycle causes a crash because SingleTickerProviderStateMixin only allows one ticker to be created.

Context / Trigger Conditions

Error message:

_YourStateClass is a SingleTickerProviderStateMixin but multiple tickers were created.
A SingleTickerProviderStateMixin can only be used as a TickerProvider once.
If a State is used for multiple AnimationController objects, or if it is passed to other
objects and those objects might use it more than one time in total, then instead of mixing
in a SingleTickerProviderStateMixin, use a regular TickerProviderStateMixin.

When this happens:

• You dispose and recreate a TabController when tab count changes
• You have tabs that conditionally appear based on async state (e.g., Riverpod providers)
• Feature flags control which tabs are visible
• Tab visibility depends on API availability or user permissions

Solution

Step 1: Change the Mixin

Replace SingleTickerProviderStateMixin with TickerProviderStateMixin:

// WRONG - crashes when TabController is recreated
class _MyScreenState extends State<MyScreen>
    with SingleTickerProviderStateMixin {

// CORRECT - allows multiple TabControllers over widget lifetime
class _MyScreenState extends State<MyScreen>
    with TickerProviderStateMixin {

Step 2: Track Tab Count State

Keep a state variable to track the current tab configuration:

bool? _lastFeatureAvailable;
TabController? _tabController;

int get _tabCount => (_lastFeatureAvailable ?? false) ? 4 : 3;

void _initTabController() {
  _tabController?.removeListener(_onTabChanged);
  _tabController?.dispose();
  _tabController = TabController(
    length: _tabCount,
    vsync: this,
  );
  _tabController!.addListener(_onTabChanged);
}

Step 3: Synchronously Rebuild on State Change

When the condition changes, rebuild the TabController synchronously (not in postFrameCallback):

@override
Widget build(BuildContext context) {
  // Watch the async state
  final featureAvailableAsync = ref.watch(featureAvailableProvider);
  final featureAvailable = featureAvailableAsync.asData?.value ?? false;

  // Rebuild TabController SYNCHRONOUSLY when state changes
  if (_lastFeatureAvailable != featureAvailable) {
    _lastFeatureAvailable = featureAvailable;
    _initTabController();  // Synchronous rebuild
  }

  // Build tabs using the SAME variable for consistency
  return TabBar(
    controller: _tabController,
    tabs: [
      const Tab(text: 'Tab 1'),
      const Tab(text: 'Tab 2'),
      if (_lastFeatureAvailable ?? false) const Tab(text: 'Optional Tab'),
      const Tab(text: 'Tab 3'),
    ],
  );
}

Step 4: Keep Tabs and TabBarView in Sync

Use the same state variable for both the tabs list and TabBarView children:

// TabBar tabs
tabs: [
  const Tab(text: 'Always'),
  if (_lastFeatureAvailable ?? false) const Tab(text: 'Conditional'),
],

// TabBarView children - MUST match tabs exactly
TabBarView(
  controller: _tabController,
  children: [
    const AlwaysTab(),
    if (_lastFeatureAvailable ?? false) const ConditionalTab(),
  ],
),

Verification

After applying the fix:

1. No crash when the async state changes
2. Tabs appear/disappear correctly (not just grayed out)
3. Tab selection state is preserved (clamped to valid range)
4. No visual glitches during transition

Example

Real-world example - hiding a "Classics" tab when REST API is unavailable:

class _ExploreScreenState extends ConsumerState<ExploreScreen>
    with TickerProviderStateMixin {  // NOT SingleTickerProviderStateMixin

  TabController? _tabController;
  bool? _lastClassicsAvailable;

  int get _tabCount => (_lastClassicsAvailable ?? false) ? 4 : 3;

  void _initTabController() {
    final savedTabIndex = ref.read(exploreTabIndexProvider);
    final validIndex = savedTabIndex.clamp(0, _tabCount - 1);
    _tabController?.removeListener(_onTabChanged);
    _tabController?.dispose();
    _tabController = TabController(
      length: _tabCount,
      vsync: this,
      initialIndex: validIndex,
    );
    _tabController!.addListener(_onTabChanged);
  }

  @override
  Widget build(BuildContext context) {
    final classicsAvailable =
        ref.watch(classicVinesAvailableProvider).asData?.value ?? false;

    if (_lastClassicsAvailable != classicsAvailable) {
      _lastClassicsAvailable = classicsAvailable;
      _initTabController();  // Synchronous, not postFrameCallback
    }

    return Column(
      children: [
        TabBar(
          controller: _tabController,
          tabs: [
            const Tab(text: 'New'),
            const Tab(text: 'Popular'),
            if (_lastClassicsAvailable ?? false) const Tab(text: 'Classics'),
            const Tab(text: 'Lists'),
          ],
        ),
        Expanded(
          child: TabBarView(
            controller: _tabController,
            children: [
              const NewVideosTab(),
              const PopularVideosTab(),
              if (_lastClassicsAvailable ?? false) const ClassicsTab(),
              const ListsTab(),
            ],
          ),
        ),
      ],
    );
  }
}

Notes

• Why not postFrameCallback? Using addPostFrameCallback to rebuild the TabController causes a frame where the TabController length doesn't match the tabs list, resulting in tabs appearing "grayed out" or other visual glitches.

• Performance: TickerProviderStateMixin has slightly more overhead than SingleTickerProviderStateMixin, but it's negligible for typical use cases.

• Tab index preservation: When reducing tab count, clamp the current index to avoid out-of-bounds errors: savedIndex.clamp(0, newTabCount - 1).

• Riverpod patterns: When using Riverpod async providers, remember that asyncValue.asData?.value ?? false gives you a synchronous default while loading.

References

• Flutter TabController class
• TickerProviderStateMixin
• SingleTickerProviderStateMixin