A flexible and customizable breadcrumb navigation widget for Flutter applications.

zeba_academy_breadcrumb provides a clean and reusable way to display navigation paths such as:

Home > Products > Details

The package supports clickable navigation items, custom separators, icons, styling, themes, horizontal scrolling, and accessibility-friendly semantics.

Features

Simple breadcrumb navigation
Clickable breadcrumb items
Custom separators
Custom separator builders
Optional icons
Active/current item styling
Disabled item styling
Custom text styles
Theme configuration
Horizontal scrolling for long breadcrumb paths
Custom item tap callbacks
Accessibility-friendly semantic labels
Immutable breadcrumb item model
No external dependencies
Lightweight and production-ready
Fully customizable

Installation

Add the package to your pubspec.yaml:

dependencies:
  zeba_academy_breadcrumb: ^0.0.1

Then run:

flutter pub get

Or run:

flutter pub add zeba_academy_breadcrumb

Import

import 'package:zeba_academy_breadcrumb/zeba_academy_breadcrumb.dart';

Basic Usage

import 'package:flutter/material.dart';
import 'package:zeba_academy_breadcrumb/zeba_academy_breadcrumb.dart';

class ExamplePage extends StatelessWidget {
  const ExamplePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Breadcrumb Example'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: ZebaBreadcrumb(
          items: [
            ZebaBreadcrumbItem(
              label: 'Home',
              onTap: () {
                debugPrint('Home tapped');
              },
            ),
            ZebaBreadcrumbItem(
              label: 'Products',
              onTap: () {
                debugPrint('Products tapped');
              },
            ),
            const ZebaBreadcrumbItem(
              label: 'Details',
            ),
          ],
        ),
      ),
    );
  }
}

A typical breadcrumb trail:

Home > Products > Details

Can be created with:

ZebaBreadcrumb(
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Products',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Details',
    ),
  ],
)

The final breadcrumb item is treated as the current page.

Custom Separators

You can customize the separator:

ZebaBreadcrumb(
  separator: const Icon(
    Icons.chevron_right,
    size: 18,
  ),
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Products',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Details',
    ),
  ],
)

You can also use a text separator:

ZebaBreadcrumb(
  separator: const Text('/'),
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Blog',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Article',
    ),
  ],
)

Custom Separator Builder

Use separatorBuilder when you need different separators or dynamic separator widgets.

ZebaBreadcrumb(
  separatorBuilder: (context, index) {
    return const Text(
      '→',
      style: TextStyle(
        fontWeight: FontWeight.bold,
      ),
    );
  },
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Category',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Product',
    ),
  ],
)

The index represents the separator position.

Breadcrumbs with Icons

Add icons to individual breadcrumb items:

ZebaBreadcrumb(
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      icon: const Icon(
        Icons.home,
        size: 16,
      ),
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Settings',
      icon: const Icon(
        Icons.settings,
        size: 16,
      ),
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Profile',
      icon: Icon(
        Icons.person,
        size: 16,
      ),
    ),
  ],
)

Styling

Customize breadcrumb item styles:

ZebaBreadcrumb(
  itemStyle: const TextStyle(
    color: Colors.blue,
    fontSize: 15,
  ),
  activeItemStyle: const TextStyle(
    color: Colors.black,
    fontSize: 15,
    fontWeight: FontWeight.bold,
  ),
  disabledItemStyle: const TextStyle(
    color: Colors.grey,
  ),
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Products',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Details',
    ),
  ],
)

For reusable styling, use ZebaBreadcrumbThemeData:

ZebaBreadcrumb(
  theme: const ZebaBreadcrumbThemeData(
    itemStyle: TextStyle(
      fontSize: 14,
      color: Colors.blue,
    ),
    activeItemStyle: TextStyle(
      fontSize: 14,
      fontWeight: FontWeight.bold,
    ),
    disabledItemStyle: TextStyle(
      color: Colors.grey,
    ),
    itemSpacing: 6,
    separatorSpacing: 4,
  ),
  items: [
    ZebaBreadcrumbItem(
      label: 'Dashboard',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Users',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Profile',
    ),
  ],
)

Item Tap Callbacks

You can handle item taps directly:

ZebaBreadcrumbItem(
  label: 'Home',
  onTap: () {
    Navigator.of(context).pop();
  },
)

Or use the parent-level callback:

ZebaBreadcrumb(
  onItemTap: (item, index) {
    debugPrint(
      'Tapped ${item.label} at index $index',
    );
  },
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Products',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Details',
    ),
  ],
)

Disabled Items

Breadcrumb items can be disabled:

const ZebaBreadcrumbItem(
  label: 'Unavailable',
  enabled: false,
)

Disabled items:

Cannot be tapped
Use the disabled text style
Remain visible in the breadcrumb trail

Custom Semantic Labels

Improve accessibility with a custom semantic label:

ZebaBreadcrumbItem(
  label: 'Settings',
  semanticLabel: 'Navigate to application settings',
  onTap: () {},
)

The package uses Flutter semantics to provide better support for accessibility technologies.

Horizontal Scrolling

Breadcrumbs automatically support horizontal scrolling by default.

ZebaBreadcrumb(
  scrollable: true,
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Category',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Subcategory',
      onTap: () {},
    ),
    ZebaBreadcrumbItem(
      label: 'Product',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Details',
    ),
  ],
)

To disable scrolling:

ZebaBreadcrumb(
  scrollable: false,
  items: [
    // Breadcrumb items
  ],
)

Padding and Spacing

Customize the outer padding:

ZebaBreadcrumb(
  padding: const EdgeInsets.all(16),
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Current',
    ),
  ],
)

Customize item and separator spacing:

ZebaBreadcrumb(
  itemSpacing: 12,
  separatorSpacing: 6,
  items: [
    ZebaBreadcrumbItem(
      label: 'Home',
      onTap: () {},
    ),
    const ZebaBreadcrumbItem(
      label: 'Current',
    ),
  ],
)

API Reference

`ZebaBreadcrumb`

Property	Type	Description
`items`	`List<ZebaBreadcrumbItem>`	Breadcrumb items
`separator`	`Widget`	Default separator widget
`separatorBuilder`	`Widget Function(BuildContext, int)?`	Custom separator builder
`itemSpacing`	`double`	Spacing around items
`separatorSpacing`	`double`	Spacing around separators
`itemStyle`	`TextStyle?`	Style for regular items
`activeItemStyle`	`TextStyle?`	Style for current item
`disabledItemStyle`	`TextStyle?`	Style for disabled items
`separatorStyle`	`TextStyle?`	Separator text style
`theme`	`ZebaBreadcrumbThemeData?`	Theme configuration
`scrollable`	`bool`	Enables horizontal scrolling
`padding`	`EdgeInsetsGeometry`	Outer padding
`onItemTap`	`Function?`	Parent-level tap callback

`ZebaBreadcrumbItem`

Property	Type	Description
`label`	`String`	Breadcrumb label
`onTap`	`VoidCallback?`	Item tap callback
`icon`	`Widget?`	Optional leading icon
`enabled`	`bool`	Whether the item is enabled
`semanticLabel`	`String?`	Accessibility label

`ZebaBreadcrumbThemeData`

Property	Type	Description
`itemStyle`	`TextStyle?`	Regular item style
`activeItemStyle`	`TextStyle?`	Current item style
`disabledItemStyle`	`TextStyle?`	Disabled item style
`separatorStyle`	`TextStyle?`	Separator style
`separatorColor`	`Color?`	Separator color
`itemSpacing`	`double`	Item spacing
`separatorSpacing`	`double`	Separator spacing

Design Philosophy

zeba_academy_breadcrumb is designed to be:

Simple to use
Easy to customize
Lightweight
Dependency-free
Accessible
Flexible for different UI designs
Suitable for production applications

The package intentionally provides a focused API without forcing a specific navigation architecture.

Testing

Run static analysis:

flutter analyze

Run tests:

flutter test

Validate the package before publishing:

flutter pub publish --dry-run

Requirements

Flutter >=1.17.0
Dart ^3.12.0

License

This project is licensed under the GNU General Public License v3.0.

You may use, modify, and distribute this software under the terms of the GPL v3.0.

See the LICENSE file for the complete license text.

About Me

✨ I’m Sufyan bin Uzayr, an open-source developer passionate about building and sharing meaningful projects.

You can learn more about me and my work at sufyanism.com or connect with me on LinkedIn.

Your All-in-One Learning Hub!

🚀 Explore courses and resources in coding, tech, and development at zeba.academy and code.zeba.academy.

Empower yourself with practical skills through curated tutorials, real-world projects, and hands-on experience. Level up your tech game today! 💻✨

Zeba Academy is a learning platform dedicated to coding, technology, and development.

➡ Visit our main site: zeba.academy

➡ Explore hands-on courses and resources at: code.zeba.academy

➡ Check out our YouTube for more tutorials: zeba.academy

➡ Follow us on Instagram: zeba.academy

Thank you for visiting!

Features

Installation

Import

Basic Usage

Custom Separators

Custom Separator Builder

Styling

Item Tap Callbacks

Disabled Items

Custom Semantic Labels

Horizontal Scrolling

Padding and Spacing

API Reference

`ZebaBreadcrumb`

`ZebaBreadcrumbItem`

`ZebaBreadcrumbThemeData`

Design Philosophy

Testing

Requirements

License

About Me

Your All-in-One Learning Hub!

Libraries

zeba_academy_breadcrumb package

Zeba Academy Breadcrumb

Features

Installation

Import

Basic Usage

Breadcrumb Navigation

Custom Separators

Custom Separator Builder

Breadcrumbs with Icons

Styling

Breadcrumb Theme

Item Tap Callbacks

Disabled Items

Custom Semantic Labels

Horizontal Scrolling

Padding and Spacing

API Reference

ZebaBreadcrumb

ZebaBreadcrumbItem

ZebaBreadcrumbThemeData

Design Philosophy

Testing

Requirements

License

About Me

Your All-in-One Learning Hub!

Libraries

zeba_academy_breadcrumb package

`ZebaBreadcrumb`

`ZebaBreadcrumbItem`

`ZebaBreadcrumbThemeData`