## Overview

Enables you to navigate from one page to another without using the workspace navigation menu.

The Navigation Tile Widget provides visual, icon-based navigation through page hierarchies. It displays a reference page and its child pages as clickable tiles, where each tile shows the page's icon and name. The widget highlights the currently active page and automatically adapts its display for different screen sizes - showing horizontal tiles on desktop and a dropdown menu on mobile devices.

Pages must be explicitly marked to appear in the navigation through a boolean flag ("Show in tile navigation"), giving administrators fine-grained control over which pages are included in the navigation interface.

## Use Cases

### Page Hierarchy Navigation
Create navigation bars that display a parent page and all its child pages as tiles, allowing users to navigate between sibling pages without returning to the workspace navigation. This is particularly useful for dashboards, overview pages, or section landing pages where related pages need to be quickly accessible.

### Section-Based Workspaces
Build consistent navigation across multiple related pages at the same level in the hierarchy. Users can maintain context within a specific workspace section while easily switching between pages that share a common parent.

### Workspace Homepage Navigation
Display top-level sections of a workspace from the root page, providing quick access to main workspace areas. This serves as an alternative to traditional menu-based navigation and works well for workspaces organized into clear sections.

### Contextual Page Navigation
Navigate between pages that are related to the current page context. The widget can show navigation options that are contextually relevant based on the embedding page's position in the hierarchy.

## Design Considerations

### When to Use This Widget

- You have a group of related pages that users frequently navigate between
- You want to provide visual, icon-based navigation instead of text-based menus
- You're building section-based workspaces with clear page hierarchies
- You need navigation that adapts to mobile devices automatically

### When NOT to Use This Widget

- For deep navigation hierarchies (more than 2-3 levels deep)
- When you have many pages at the same level (tiles work best with 3-8 items)
- For navigation that doesn't follow the page hierarchy structure
- When standard workspace navigation is sufficient for your use case

### Reference Page Strategies

The widget supports three reference page modes that determine which pages are displayed:

**Parent Page Mode**: The most common pattern - displays siblings of the embedding page. If the widget is on "Team A", it shows the parent's children (Team A, Team B, Team C). Use this for lateral navigation between related pages at the same level.

**Workspace Home Mode**: Displays top-level sections of the workspace. This creates consistent top-level navigation across all pages in the workspace, regardless of where the widget is embedded.

**Embedding Page Mode**: Displays children of the current page. Use this for drilling down into sub-sections, where the embedding page serves as the parent for a group of child pages.

### Page Visibility Control

The widget requires explicit opt-in for pages to appear as tiles. Each page has a "Show in tile navigation" attribute that administrators must enable. This provides:

- Fine-grained control over navigation structure
- Ability to hide organizational pages that shouldn't be direct navigation targets
- Protection against accidentally exposing internal pages

### Responsive Behavior

The widget automatically adapts its display based on screen size. Desktop and tablet users see horizontal rows of square tiles with icons, while mobile users see a compact dropdown menu with the current page name as the trigger. This ensures usability across all device types without requiring separate mobile configuration.

## Common Pitfalls

- Creating too many navigation tiles (more than 8) can overwhelm users and reduce visual clarity
- Forgetting to enable the "Show in tile navigation" flag on pages will result in them not appearing in the widget
- Using deep hierarchies with this widget - it works best for flat, shallow navigation structures
- Not considering whether the reference page itself should be included as a navigation target

## Related Widgets

- **Breadcrumb Widget** - Provides path-based navigation showing the current page's location in the hierarchy; better for showing where users are rather than lateral navigation between siblings
- **Standard Workspace Navigation** - cplace's built-in workspace menu provides comprehensive navigation for complex workspace structures with deep hierarchies