## Overview

Shows the hierarchical path to the home page of the workspace.

The Breadcrumbs Widget automatically generates and displays a hierarchical navigation trail showing the path from the current page to the workspace root. The breadcrumbs are presented as clickable links with a distinctive arrow-style visual design, helping users understand their location within the page structure and navigate quickly between hierarchical levels.

The widget operates entirely automatically by analyzing the page hierarchy - no configuration is needed for basic functionality. The breadcrumb path is rendered from root to current page (e.g., "Project > Sprint > Feature > Task"), with each level clickable for instant navigation.

## Use Cases

### Hierarchical Navigation
When users are viewing deeply nested pages within a project or organizational structure, the breadcrumbs provide a clear visual path showing how the current page fits into the larger hierarchy. Users can click any level in the path to navigate directly to that parent page without using browser back buttons.

**Example**: In a project management workspace, a user viewing a test document can see and navigate through the full path: Sprint > Feature > QA Phase > Test Documents.

### Contextual Awareness
The widget helps users understand the context of the current page by showing its position within the overall structure. This is particularly valuable in complex workspaces where pages may have multiple levels of nesting.

**Example**: A team member opening a shared link to a specific document can immediately see which project, phase, and feature it belongs to, providing essential context without requiring additional investigation.

### Quick Parent Access
Instead of navigating through multiple back button clicks or searching for parent pages, users can jump directly to any ancestor page in the hierarchy with a single click. This streamlines navigation workflows in deep hierarchies.

**Example**: From a deeply nested configuration page, a user can jump directly to the workspace home page or any intermediate level without multiple navigation steps.

### Custom Navigation Extensions
Organizations can extend the automatic hierarchy with additional navigation entry points that aren't part of the direct parent-child path. This allows for adding contextual pages like dashboards or overview pages at the beginning of the breadcrumb trail.

**Example**: Add a "Team Dashboard" link at the start of all breadcrumb trails so users always have quick access to the team's main overview page, regardless of where they are in the hierarchy.

## Design Considerations

### When to Use This Widget
Use the Breadcrumbs Widget when:
- Your workspace has hierarchical page structures with 2 or more levels
- Users need to understand their location within the page hierarchy
- Quick navigation to parent pages is important for user workflows
- You want to provide consistent navigation patterns across all pages

### When Not to Use This Widget
Consider alternatives when:
- Your workspace uses flat structures without parent-child relationships
- Pages are accessed primarily through search rather than hierarchical navigation
- The page hierarchy is shallow (only 1-2 levels deep) and doesn't provide meaningful context

### Placement Considerations
The widget is designed with no frame and no padding for seamless integration into page layouts. It's typically placed:
- At the top of page layouts, below the page title/header
- As a horizontal navigation bar spanning the full page width
- Before the main content area to provide immediate contextual awareness

The arrow-style visual design with alternating colors makes it immediately recognizable as navigation, distinct from other page content.

## Common Pitfalls

### Non-Page Contexts
The widget only works when embedded on Page entities. When placed in type definition layouts for non-Page types, the widget will render empty since it cannot determine a hierarchical path. Ensure the widget is only used in layouts that display Page entities.

### Over-Extension with Additional Pages
While the widget supports adding additional navigation links at the beginning of the breadcrumb trail, overusing this feature can clutter the navigation path and reduce clarity. Keep additional pages limited to truly essential entry points (1-2 maximum).

## Related Patterns

### Page Hierarchy Navigation
The breadcrumbs widget complements hierarchical structures but doesn't replace other navigation patterns. Consider combining with:
- Tree navigation widgets for exploring sibling and child pages
- Search widgets for cross-hierarchy page discovery
- Related pages widgets for non-hierarchical connections

### Layout Integration
Since the widget has no frame or padding, it integrates seamlessly with page layouts:
- Place in a dedicated navigation row at the top of layouts
- Combine with page title widgets for complete page context
- Use consistent placement across type layouts for predictable navigation