Pending Review

Pending Review from User Experience (UX)

Side Nav Component

Overview

The Side Nav component provides a dedicated navigation container for organizing hierarchical navigation items in a vertical sidebar layout. It enables users to navigate through different sections of an application while maintaining visual hierarchy and selection state management with responsive design considerations.

Core Capabilities

Vertical Navigation Structure - Dedicated sidebar container with proper spacing and visual hierarchy for navigation items
Dynamic Heading System - Configurable heading display with slot-based customization and typography integration
Selection State Management - Automatic handling of item selection states with single-selection behavior enforcement
Responsive Layout Integration - Dynamic height adjustment based on viewport changes and container positioning
List Item Integration - Seamless integration with PWC List Item components for consistent navigation patterns
Accessibility Support - Proper semantic structure with keyboard navigation and screen reader compatibility

When to use Side Nav:

Primary Navigation - Main application navigation that requires persistent visibility and hierarchical organization
Section-Based Interfaces - Applications with distinct sections that benefit from sidebar navigation patterns
Dashboard Layouts - Administrative interfaces where navigation needs to remain accessible alongside main content
Multi-Level Navigation - Complex navigation structures that require nested organization and clear visual hierarchy

When not to use Side Nav:

Simple Page Navigation - Use header navigation or breadcrumbs for straightforward page-to-page navigation
Mobile-First Interfaces - Consider collapsible navigation patterns for mobile-optimized experiences
Temporary Navigation - Use dropdown menus or modals for contextual or temporary navigation needs

Basic Implementation

React 18React 19+AngularPure JavaScript

import React from 'react';
import { PwcSideNav, PwcListItem } from '@progress-i360/pwc-react';

function AppSideNav() {
  return (
      <PwcSideNav heading="Navigation">
        <PwcListItem label="Dashboard" selected />
        <PwcListItem label="Analytics" />
        <PwcListItem label="Settings" />
      </PwcSideNav>
  );
}

import '@progress-i360/progress-web-components/side-nav';
import '@progress-i360/progress-web-components/list-item';

function NavigationSidebar() {
  return (
      <pwc-side-nav heading="Menu">
        <pwc-list-item label="Home" selected></pwc-list-item>
        <pwc-list-item label="Projects"></pwc-list-item>
        <pwc-list-item label="Reports"></pwc-list-item>
      </pwc-side-nav>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@progress-i360/progress-web-components/side-nav';
import '@progress-i360/progress-web-components/list-item';

@Component({
  selector: 'side-nav-demo',
  template: `
    <div style="max-width: 300px; margin: 0 auto; padding: 20px;">
      <h3>Side Navigation Demo</h3>
      <p>Click items to navigate between sections</p>

      <pwc-side-nav heading="Main Navigation">
        <pwc-list-item 
          label="Dashboard" 
          icon="chart-bar"
          [selected]="currentSection === 'dashboard'"
          (pwc-click)="navigateToSection('dashboard')">
        </pwc-list-item>
        <pwc-list-item 
          label="Analytics" 
          icon="analytics"
          [selected]="currentSection === 'analytics'"
          (pwc-click)="navigateToSection('analytics')">
        </pwc-list-item>
        <pwc-list-item 
          label="Reports" 
          icon="file-text"
          [selected]="currentSection === 'reports'"
          (pwc-click)="navigateToSection('reports')">
        </pwc-list-item>
        <pwc-list-item 
          label="Settings" 
          icon="cog"
          [selected]="currentSection === 'settings'"
          (pwc-click)="navigateToSection('settings')">
        </pwc-list-item>
      </pwc-side-nav>

      <div style="margin-top: 16px; padding: 12px; background: #f5f5f5; border-radius: 4px;">
        <strong>Current Section:</strong> {{ getCurrentSectionName() }}
      </div>
    </div>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class SideNavDemo {
  currentSection = 'dashboard';

  navigateToSection(section: string): void {
    this.currentSection = section;
    console.log(`Navigated to: ${section}`);
  }

  getCurrentSectionName(): string {
    return this.currentSection.charAt(0).toUpperCase() + this.currentSection.slice(1);
  }
}

// Create side navigation with heading
const sideNav = document.createElement('pwc-side-nav');
sideNav.setAttribute('heading', 'Main Navigation');

// Add navigation items with selection state
const navItems = ['Dashboard', 'Analytics', 'Settings'];
navItems.forEach((label, index) => {
  const listItem = document.createElement('pwc-list-item');
  listItem.setAttribute('label', label);
  if (index === 0) listItem.selected = true; // First item selected
  sideNav.appendChild(listItem);
});

document.body.appendChild(sideNav);

Usage Patterns

Persistent Navigation - Always-visible sidebar navigation that remains accessible across different application views and states
Hierarchical Organization - Multi-level navigation structures with clear parent-child relationships and visual indentation
State-Driven Selection - Dynamic highlighting of current section based on application routing and user navigation
Responsive Adaptation - Flexible layout behavior that adapts to different screen sizes while maintaining usability

Best Practices

Content Strategy Guidelines

Clear Navigation Labels - Use descriptive, concise labels that clearly indicate the destination or section content
Logical Hierarchy - Organize navigation items in a logical order that matches user mental models and task flows
Consistent Iconography - Apply consistent visual indicators and icons that support navigation understanding
Visual Grouping - Use headings and visual separators to group related navigation items and reduce cognitive load

Performance Optimization

Efficient Event Handling - Implement proper event delegation to minimize memory usage with multiple navigation items
Responsive Calculations - Optimize viewport-based height calculations to prevent unnecessary layout recalculations
Selective Rendering - Only render visible navigation items for large navigation structures to maintain performance
State Management - Use efficient state updates to prevent unnecessary re-renders when selection states change

Integration Architecture

Router Integration - Seamlessly integrate with application routing to maintain navigation state consistency
Theme Compatibility - Ensure navigation styling works across light and dark theme variations with proper token usage
Layout Coordination - Design navigation to work harmoniously with main content areas and responsive breakpoints
Accessibility Integration - Implement proper ARIA roles and keyboard navigation patterns for comprehensive accessibility

Common Use Cases

Data Table Headers

Section Navigation - Navigate between different data categories and table views with persistent selection indication
Filter Integration - Combine navigation with filtering controls to provide context-aware data organization
Action Context - Provide navigation context for table-related actions and bulk operations

Search Result Sections

Category Navigation - Navigate between different search result categories with clear section identification
Refinement Controls - Integrate search refinement options within the navigation structure for enhanced discoverability
Result Context - Maintain navigation context while users explore different search result sections

Dashboard Sections - Navigate between different dashboard views and widget collections with state preservation
Configuration Access - Provide quick access to dashboard configuration options through integrated navigation
Data Source Navigation - Navigate between different data sources and visualization contexts within dashboard layouts

Troubleshooting

Common Issues

Actions Not Triggering

Problem: Navigation items don't respond to clicks or selection events aren't firing properly

Solutions:

Verify that list items are properly slotted within the side nav component structure
Check that event listeners are correctly attached to handle pwc-click events from list items
Ensure that custom event propagation isn't being prevented by parent container components

Actions Not Visible

Problem: Navigation items don't appear or selection states aren't updating visually

Solutions:

Confirm that list items are properly imported and registered in the application bundle
Check that the side nav container has proper dimensions and isn't hidden by CSS overflow settings
Verify that selection state management is working correctly with proper boolean attribute handling

Layout Issues

Problem: Side navigation doesn't size correctly or doesn't adapt to viewport changes

Solutions:

Check that responsive height calculations are working with proper window resize event handling
Verify that CSS flexbox properties are correctly applied for vertical layout organization
Ensure that the side nav container has proper positioning relative to its parent layout

Icon Problems

Problem: Navigation item icons don't display or heading typography doesn't render correctly

Solutions:

Confirm that list item components have proper icon attribute configuration
Check that typography rendering functions are correctly imported and applied for heading display
Verify that design token CSS variables are available for proper visual styling

Implementation Support

Framework Integration - Complete examples and integration guides for React, Angular, and vanilla JavaScript implementations
Design System Integration - Full compatibility with PWC design tokens for consistent navigation styling and responsive behavior
Accessibility Compliance - Built-in support for screen readers, keyboard navigation, and WCAG 2.1 AA compliance standards

Resources

Storybook Documentation

For comprehensive API documentation, interactive examples, and testing tools: 📖 View Complete API Documentation in Storybook →

This guide provides high-level implementation guidance. For detailed API specifications and interactive examples, visit our Storybook documentation.

Side Nav Component

Overview

Core Capabilities

Basic Implementation

Usage Patterns

Best Practices

Content Strategy Guidelines

Performance Optimization

Integration Architecture

Common Use Cases

Data Table Headers

Search Result Sections

Dashboard Widget Headers

Troubleshooting

Common Issues

Actions Not Triggering

Actions Not Visible

Layout Issues

Icon Problems

Implementation Support

Resources

Resources

Storybook Documentation