common_widget_kit 0.1.0

Reusable Flutter widgets with an enterprise-style configurable bottom navigation component.

common_widget_kit

Reusable Flutter common widgets package. The first enterprise-ready module in this package is a configurable bottom navigation component with:

• custom labels, icons, and selected icons
• center action button support
• theme, layout, and animation configuration
• mobile/web consistent layout strategy
• compatibility wrapper for the original CurvedBottomNavigationBar

Install

For pub.dev:

dependencies:
  common_widget_kit: ^0.1.0

For local integration during development:

dependencies:
  common_widget_kit:
    path: ../common_widget_kit

Then import:

import 'package:common_widget_kit/common_widget_kit.dart';

Run the example app locally:

cd example
flutter run

Recommended API

CommonBottomNavigationBar(
  items: const [
    CommonBottomNavigationItem(
      id: 'bookshelf',
      label: '书架',
      inactiveIcon: CupertinoIcons.book,
      activeIcon: CupertinoIcons.book_fill,
      tooltip: '书架',
    ),
    CommonBottomNavigationItem(
      id: 'stats',
      label: '统计',
      inactiveIcon: CupertinoIcons.chart_bar,
      activeIcon: CupertinoIcons.chart_bar_fill,
    ),
    CommonBottomNavigationItem(
      id: 'review',
      label: '回溯',
      inactiveIcon: Icons.blur_circular_outlined,
      activeIcon: Icons.blur_circular,
    ),
    CommonBottomNavigationItem(
      id: 'profile',
      label: '我的',
      inactiveIcon: CupertinoIcons.person,
      activeIcon: CupertinoIcons.person_fill,
    ),
  ],
  currentIndex: currentIndex,
  onItemSelected: (index) => setState(() => currentIndex = index),
  onSelectionChanged: (change) {
    debugPrint('from ${change.previousIndex} to ${change.currentIndex}');
  },
  centerAction: const CommonBottomNavigationCenterAction(
    child: Icon(CupertinoIcons.pen),
    tooltip: '新建',
  ),
  theme: const CommonBottomNavigationThemeData(),
  layout: const CommonBottomNavigationLayoutData(
    maxBarWidth: 390,
  ),
  animation: const CommonBottomNavigationAnimationData(),
)

Scaffold Container

Use the scaffold wrapper when you want to bind the navigation bar directly to a page list:

const items = [
  CommonBottomNavigationItem(
    id: 'bookshelf',
    label: '书架',
    inactiveIcon: CupertinoIcons.book,
    activeIcon: CupertinoIcons.book_fill,
  ),
  CommonBottomNavigationItem(
    id: 'stats',
    label: '统计',
    inactiveIcon: CupertinoIcons.chart_bar,
    activeIcon: CupertinoIcons.chart_bar_fill,
  ),
  CommonBottomNavigationItem(
    id: 'review',
    label: '回溯',
    inactiveIcon: Icons.blur_circular_outlined,
    activeIcon: Icons.blur_circular,
  ),
  CommonBottomNavigationItem(
    id: 'profile',
    label: '我的',
    inactiveIcon: CupertinoIcons.person,
    activeIcon: CupertinoIcons.person_fill,
  ),
];

const pages = [
  BookshelfPage(),
  StatisticsPage(),
  ReviewPage(),
  ProfilePage(),
];

CommonBottomNavigationScaffold(
  items: items,
  pages: pages,
  centerAction: const CommonBottomNavigationCenterAction(
    child: Icon(CupertinoIcons.pen),
  ),
)

items[index] should match pages[index]. The example app under example/lib/main.dart shows a complete pages + items setup you can copy into a real project.

Features:

• IndexedStack keeps tab pages alive by default
• supports controlled and uncontrolled index modes
• forwards theme, layout, animation, and center action config
• accepts common Scaffold slots such as appBar, drawer, and FAB

Configuration Model

CommonBottomNavigationItem

Supports:

• id
• label
• inactiveIcon
• activeIcon
• badgeData
• badge
• tooltip
• semanticLabel
• enabled
• onTap

Badge recommendations:

• CommonBottomNavigationBadgeData.dot() for red dot reminders
• CommonBottomNavigationBadgeData.count(count: 8) for message counts
• CommonBottomNavigationBadgeData.text(text: 'NEW') for business tags

CommonBottomNavigationCenterAction

Supports:

• custom center button child
• click callback
• visibility control
• tooltip
• semantics label

CommonBottomNavigationThemeData

Use to define:

• bar background
• active pill color
• icon color
• border color
• shadow colors

CommonBottomNavigationLayoutData

Use to define:

• height and shell height
• content and horizontal padding
• center gap
• center button size
• notch geometry
• max width for web/mobile consistency
• min/max item width
• side item spacing range

CommonBottomNavigationAnimationData

Use to define:

• pill slide/scale duration and curves
• item press/slide/scale duration and curves
• icon switch duration
• label transition duration
• whether pill blur/highlight is enabled

Backward Compatibility

The package still exposes the original API:

CurvedBottomNavigationBar(...)

This wrapper maps legacy parameters into the new public configuration model, so existing projects can migrate gradually.