Breadcrumb Component - Complete Documentation

Table of Contents

• Overview
• Installation
• Basic Usage
• Inputs
• Route Configuration
• Usage Examples
• Best Practices

Overview

The ngx-st-breadcrumb component is an automatic breadcrumb navigation that generates breadcrumbs from Angular Router configuration. Features include:

• Automatic breadcrumb generation from route data
• Optional translation support (ngx-translate)
• Home icon with customizable route
• Show/hide individual breadcrumbs
• Optional link display
• Material Design icons support

Installation

npm install ngx-st-breadcrumb

Import the component:

import { NgxStBreadcrumbComponent } from 'ngx-st-breadcrumb';

// In your component
imports: [NgxStBreadcrumbComponent]

Basic Usage

1. Configure Routes with Breadcrumb Data

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    data: {
      breadcrumb: {
        label: 'Home',
        show: false  // Hide home from breadcrumb
      }
    }
  },
  {
    path: 'products',
    component: ProductsComponent,
    data: {
      breadcrumb: {
        label: 'Products',
        showLink: true
      }
    }
  },
  {
    path: 'products/:id',
    component: ProductDetailComponent,
    data: {
      breadcrumb: {
        label: 'Product Details',
        showLink: false
      }
    }
  }
];

2. Add Component to Template

<ngx-st-breadcrumb></ngx-st-breadcrumb>

Inputs

useTranslation

• Type: boolean
• Default: true
• Description: Enables/disables automatic translation of breadcrumb labels using ngx-translate. When true, labels will be passed through TranslateService.
• Requires: @ngx-translate/core package installed
• Example:

  <ngx-st-breadcrumb [useTranslation]="false"></ngx-st-breadcrumb>
  <ngx-st-breadcrumb [useTranslation]="true"></ngx-st-breadcrumb>

Route Configuration

Each route can have a breadcrumb object in its data property with the following options:

BreadcrumbData Interface

interface BreadcrumbData {
  label: string;        // Required: Display text
  show?: boolean;       // Optional: Show/hide breadcrumb (default: true)
  showLink?: boolean;   // Optional: Make breadcrumb clickable (default: true for parent routes)
}

Breadcrumb Configuration Properties

label (Required)

• Type: string
• Description: The text to display in the breadcrumb. If useTranslation is true, this will be used as a translation key.
• Example:

  data: {
    breadcrumb: {
      label: 'BREADCRUMB.PRODUCTS'  // With translation
    }
  }
    
  data: {
    breadcrumb: {
      label: 'Products'  // Without translation
    }
  }

show (Optional)

• Type: boolean
• Default: true (if not specified)
• Description: Controls whether this breadcrumb appears in the trail.
• Example:

  // Hide home route from breadcrumb trail
  data: {
    breadcrumb: {
      label: 'Home',
      show: false
    }
  }
    
  // Show all other routes (default)
  data: {
    breadcrumb: {
      label: 'Products'
      // show: true is implicit
    }
  }

showLink (Optional)

• Type: boolean
• Default: true for parent routes
• Description: Makes the breadcrumb clickable/navigable. Usually set to false for the current page.
• Example:

  // Parent route - clickable
  {
    path: 'products',
    data: {
      breadcrumb: {
        label: 'Products',
        showLink: true
      }
    }
  }
    
  // Current page - not clickable
  {
    path: 'products/:id',
    data: {
      breadcrumb: {
        label: 'Details',
        showLink: false
      }
    }
  }

Usage Examples

Example 1: Basic Setup

// app-routing.module.ts
const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    data: {
      breadcrumb: {
        label: 'Home',
        show: false
      }
    }
  },
  {
    path: 'users',
    component: UsersListComponent,
    data: {
      breadcrumb: {
        label: 'Users'
      }
    }
  },
  {
    path: 'users/:id',
    component: UserDetailComponent,
    data: {
      breadcrumb: {
        label: 'User Details',
        showLink: false
      }
    }
  }
];

<!-- app.component.html -->
<header>
  <ngx-st-breadcrumb></ngx-st-breadcrumb>
</header>

Example 2: With Translation

// Install ngx-translate
// npm install @ngx-translate/core @ngx-translate/http-loader

// app.module.ts
import { TranslateModule } from '@ngx-translate/core';

@NgModule({
  imports: [
    TranslateModule.forRoot({...})
  ]
})
export class AppModule { }

// en.json (translation file)
{
  "BREADCRUMB": {
    "HOME": "Home",
    "USERS": "Users",
    "USER_DETAILS": "User Details",
    "SETTINGS": "Settings"
  }
}

// Routes
const routes: Routes = [
  {
    path: 'users',
    data: {
      breadcrumb: {
        label: 'BREADCRUMB.USERS'  // Will be translated
      }
    }
  },
  {
    path: 'users/:id',
    data: {
      breadcrumb: {
        label: 'BREADCRUMB.USER_DETAILS'
      }
    }
  }
];

<ngx-st-breadcrumb [useTranslation]="true"></ngx-st-breadcrumb>

Example 3: Multi-Level Navigation

// Routes with nested structure
const routes: Routes = [
  {
    path: 'admin',
    component: AdminComponent,
    data: {
      breadcrumb: {
        label: 'Administration'
      }
    },
    children: [
      {
        path: 'users',
        component: AdminUsersComponent,
        data: {
          breadcrumb: {
            label: 'User Management'
          }
        },
        children: [
          {
            path: ':id',
            component: UserEditComponent,
            data: {
              breadcrumb: {
                label: 'Edit User',
                showLink: false
              }
            }
          }
        ]
      },
      {
        path: 'settings',
        component: AdminSettingsComponent,
        data: {
          breadcrumb: {
            label: 'Settings'
          }
        }
      }
    ]
  }
];

// URL: /admin/users/123
// Breadcrumb: Home > Administration > User Management > Edit User

Example 4: Conditional Breadcrumbs

// Dynamic breadcrumb based on data
const routes: Routes = [
  {
    path: 'products',
    component: ProductsComponent,
    data: {
      breadcrumb: {
        label: 'Products'
      }
    }
  },
  {
    path: 'products/:category',
    component: CategoryComponent,
    data: {
      breadcrumb: {
        label: 'Category',  // Could be dynamic in component
        show: true
      }
    }
  },
  {
    path: 'products/:category/:id',
    component: ProductDetailComponent,
    data: {
      breadcrumb: {
        label: 'Product Details',
        showLink: false
      }
    }
  }
];

Example 5: Without Translation

// app.component.ts
@Component({
  template: `
    <ngx-st-breadcrumb [useTranslation]="false"></ngx-st-breadcrumb>
  `
})
export class AppComponent { }

// Routes with plain text labels
const routes: Routes = [
  {
    path: 'dashboard',
    data: {
      breadcrumb: {
        label: 'Dashboard'  // Plain text, no translation
      }
    }
  },
  {
    path: 'reports',
    data: {
      breadcrumb: {
        label: 'Reports'
      }
    }
  }
];

Example 6: E-commerce Navigation

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    data: {
      breadcrumb: {
        label: 'Home',
        show: false
      }
    }
  },
  {
    path: 'shop',
    component: ShopComponent,
    data: {
      breadcrumb: {
        label: 'Shop',
        showLink: true
      }
    }
  },
  {
    path: 'shop/:category',
    component: CategoryComponent,
    data: {
      breadcrumb: {
        label: 'Category',
        showLink: true
      }
    }
  },
  {
    path: 'shop/:category/:subcategory',
    component: SubcategoryComponent,
    data: {
      breadcrumb: {
        label: 'Subcategory',
        showLink: true
      }
    }
  },
  {
    path: 'shop/:category/:subcategory/:productId',
    component: ProductComponent,
    data: {
      breadcrumb: {
        label: 'Product',
        showLink: false  // Current page
      }
    }
  },
  {
    path: 'cart',
    component: CartComponent,
    data: {
      breadcrumb: {
        label: 'Shopping Cart',
        showLink: false
      }
    }
  },
  {
    path: 'checkout',
    component: CheckoutComponent,
    data: {
      breadcrumb: {
        label: 'Checkout',
        showLink: false
      }
    }
  }
];

// URL: /shop/electronics/phones/iphone-13
// Breadcrumb: Home > Shop > Electronics > Phones > iPhone 13

Example 7: Admin Dashboard

const routes: Routes = [
  {
    path: 'admin',
    component: AdminLayoutComponent,
    data: {
      breadcrumb: {
        label: 'ADMIN.HOME',
        showLink: true
      }
    },
    children: [
      {
        path: 'dashboard',
        component: DashboardComponent,
        data: {
          breadcrumb: {
            label: 'ADMIN.DASHBOARD',
            showLink: false
          }
        }
      },
      {
        path: 'users',
        data: {
          breadcrumb: {
            label: 'ADMIN.USERS.TITLE'
          }
        },
        children: [
          {
            path: '',
            component: UsersListComponent,
            data: {
              breadcrumb: {
                label: 'ADMIN.USERS.LIST'
              }
            }
          },
          {
            path: 'create',
            component: UserCreateComponent,
            data: {
              breadcrumb: {
                label: 'ADMIN.USERS.CREATE',
                showLink: false
              }
            }
          },
          {
            path: ':id/edit',
            component: UserEditComponent,
            data: {
              breadcrumb: {
                label: 'ADMIN.USERS.EDIT',
                showLink: false
              }
            }
          }
        ]
      }
    ]
  }
];

Example 8: Custom Styling

@Component({
  template: `
    <ngx-st-breadcrumb class="custom-breadcrumb"></ngx-st-breadcrumb>
  `,
  styles: [`
    .custom-breadcrumb {
      padding: 1rem;
      background: #f5f5f5;
      border-radius: 4px;
    }
    
    .custom-breadcrumb ::ng-deep a {
      color: #1976d2;
      text-decoration: none;
    }
    
    .custom-breadcrumb ::ng-deep a:hover {
      text-decoration: underline;
    }
    
    .custom-breadcrumb ::ng-deep mat-icon {
      color: #666;
    }
  `]
})
export class AppComponent { }

Best Practices

1. Hide the home route from breadcrumbs if you have a home icon:

   data: {
     breadcrumb: {
       label: 'Home',
       show: false
     }
   }

2. Make parent routes clickable:

   data: {
     breadcrumb: {
       label: 'Products',
       showLink: true  // Can navigate back
     }
   }

3. Current page should not be a link:

   data: {
     breadcrumb: {
       label: 'Details',
       showLink: false  // Can't click current page
     }
   }

4. Use translation keys for multi-language support:

   data: {
     breadcrumb: {
       label: 'BREADCRUMB.PRODUCTS'
     }
   }

5. Keep labels short and meaningful:

   label: 'Products'        // Good
   label: 'Product List'    // Good
   label: 'All Products in Database'  // Too long

6. Configure breadcrumbs for all routes:

   // Even if hidden
   data: {
     breadcrumb: {
       label: 'Route Name',
       show: false
     }
   }

Component Behavior

Automatic Updates

The breadcrumb automatically updates when navigating between routes using Angular Router.

Home Icon

The component displays a home icon that navigates to '/' by default.

Separator

Uses '>' as the default separator between breadcrumb items.

Current Route

The last item in the breadcrumb trail (current page) is typically not clickable.

Translation Setup

When using useTranslation="true":

1. Install ngx-translate:

   npm install @ngx-translate/core @ngx-translate/http-loader

2. Configure TranslateModule in your app

3. Create translation files with breadcrumb keys

4. Use translation keys in route configuration

Common Patterns

Pattern 1: Simple Navigation

Home > Products > Product Details

Pattern 2: Deep Hierarchy

Home > Admin > Users > Edit User

Pattern 3: Category Navigation

Home > Shop > Electronics > Phones > iPhone

Pattern 4: Settings Navigation

Home > Settings > Profile > Security

Troubleshooting

Breadcrumbs not appearing

• Check that routes have data.breadcrumb configuration
• Verify route navigation is working
• Check that show is not set to false

Translation not working

• Verify @ngx-translate/core is installed
• Check TranslateModule is imported
• Ensure useTranslation input is true
• Verify translation keys exist in translation files

Styling issues

• Component uses Angular Material icons - ensure Material is installed
• Use ::ng-deep for deep styling if needed

This documentation covers all inputs, configuration, and usage patterns for the Breadcrumb component.