Pending Review

Pending Review from User Experience (UX)

List Item Component

Overview

The PWC List Item component provides a flexible, interactive building block for navigation menus, selection lists, and content organization interfaces. It supports customizable icons, labels, selection states, and disabled states while maintaining consistent visual design and accessibility standards across different navigation contexts within menus and side navigation components.

Core Capabilities

Interactive List Elements - Clickable list items with hover, focus, and active states that provide clear visual feedback for user interactions
Icon and Label Support - Flexible content structure with optional icons and labels, plus slot-based customization for complex content layouts
Selection State Management - Built-in selected state visualization with distinct styling to indicate current or active items in navigation contexts
Disabled State Handling - Comprehensive disabled state support with appropriate visual styling and interaction prevention for unavailable options
Size Variants - Short variant option for compact layouts and space-constrained interfaces while maintaining accessibility requirements
Container Integration - Automatic registration with parent menu and side navigation components for coordinated behavior and keyboard navigation

When to use List Item:

Build navigation menus, sidebar links, or content lists where users need to select or interact with individual items
Create selectable options in dropdown menus, contextual menus, or multi-select interfaces with clear visual feedback
Implement list-based interfaces where items need consistent styling, behavior, and accessibility features
Design navigation hierarchies where individual items need to communicate state and availability to users

When not to use List Item:

Simple text lists without interactive functionality (use standard HTML lists or typography components instead)
Complex card-based layouts where items contain multiple actions or rich content structures
Table-based data where items need column alignment and structured data presentation

Basic Implementation

React 18React 19+AngularPure JavaScript

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

function NavigationMenu() {
  const [selectedItem, setSelectedItem] = useState('home');

  return (
      <>
        <PwcListItem 
          label="Home" 
          selected={selectedItem === 'home'}
          onPwcClick={() => setSelectedItem('home')}
        />
        <PwcListItem 
          label="Profile" 
          selected={selectedItem === 'profile'}
          onPwcClick={() => setSelectedItem('profile')}
        />
        <PwcListItem 
          label="Settings" 
          selected={selectedItem === 'settings'}
          onPwcClick={() => setSelectedItem('settings')}
        />
      </>
  );
}

export default NavigationMenu;

import { useState } from 'react';
import '@progress-i360/progress-web-components/list-item';

function InteractiveList() {
  const [selectedItem, setSelectedItem] = useState('dashboard');

  return (
      <>
        <pwc-list-item 
          label="Dashboard" 
          selected={selectedItem === 'dashboard'}
          onPwcClick={() => setSelectedItem('dashboard')}
        ></pwc-list-item>
        <pwc-list-item 
          label="Projects" 
          selected={selectedItem === 'projects'}
          onPwcClick={() => setSelectedItem('projects')}
        ></pwc-list-item>
        <pwc-list-item 
          label="Settings" 
          selected={selectedItem === 'settings'}
          onPwcClick={() => setSelectedItem('settings')}
        ></pwc-list-item>
        <pwc-list-item 
          label="Archive" 
          disabled
        ></pwc-list-item>
      </>
  );
}

export default InteractiveList;

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

@Component({
  selector: 'list-item-demo',
  template: `
    <div style="max-width: 400px; margin: 0 auto; padding: 20px;">
      <h3>List Item Demo</h3>
      <p>Interactive list with selectable and disabled items</p>

      <div style="border: 1px solid #ddd; border-radius: 8px; overflow: hidden;">
        <pwc-list-item 
          *ngFor="let item of listItems; trackBy: trackByFn"
          [label]="item.label" 
          [icon]="item.icon"
          [selected]="item.selected"
          [disabled]="item.disabled"
          (pwc-click)="selectItem(item.id)">
        </pwc-list-item>
      </div>

      <div style="margin-top: 16px; display: flex; gap: 8px;">
        <pwc-button 
          label="Add Item" 
          variant="primary"
          (pwc-click)="addItem()">
        </pwc-button>
        <pwc-button 
          label="Toggle First Item" 
          variant="outline"
          (pwc-click)="toggleFirstItem()">
        </pwc-button>
      </div>

      <div style="margin-top: 16px; padding: 12px; background: #f5f5f5; border-radius: 4px;">
        <strong>Selected:</strong> {{ getSelectedItem()?.label || 'None' }}
      </div>
    </div>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ListItemDemo {
  private nextId = 4;

  listItems = [
    { id: 1, label: 'Dashboard', icon: 'tachometer-alt', selected: true, disabled: false },
    { id: 2, label: 'Reports', icon: 'file-alt', selected: false, disabled: false },
    { id: 3, label: 'Settings', icon: 'cog', selected: false, disabled: true }
  ];

  selectItem(id: number): void {
    this.listItems.forEach(item => {
      item.selected = item.id === id;
    });
    console.log(`Selected item: ${id}`);
  }

  addItem(): void {
    this.listItems.push({
      id: this.nextId++,
      label: `New Item ${this.nextId - 1}`,
      icon: 'plus',
      selected: false,
      disabled: false
    });
  }

  toggleFirstItem(): void {
    if (this.listItems.length > 0) {
      this.listItems[0].disabled = !this.listItems[0].disabled;
    }
  }

  getSelectedItem() {
    return this.listItems.find(item => item.selected);
  }

  trackByFn(index: number, item: any) {
    return item.id;
  }
}

// Create navigation list items with selection state
const homeItem = document.createElement('pwc-list-item');
homeItem.setAttribute('label', 'Home');
homeItem.setAttribute('icon', 'home');
homeItem.selected = true; // Set as initially selected

const profileItem = document.createElement('pwc-list-item');
profileItem.setAttribute('label', 'Profile');
profileItem.setAttribute('icon', 'user');

const settingsItem = document.createElement('pwc-list-item');
settingsItem.setAttribute('label', 'Settings');
settingsItem.setAttribute('icon', 'settings');
settingsItem.disabled = true; // Disabled state

// Handle selection changes with click events
let selectedItem = homeItem;

function handleItemClick(newItem) {
  selectedItem.selected = false; // Deselect current
  selectedItem = newItem;
  newItem.selected = true; // Select new item
  console.log('Selected:', newItem.getAttribute('label'));
}

// Add click event listeners
homeItem.addEventListener('pwc-click', () => handleItemClick(homeItem));
profileItem.addEventListener('pwc-click', () => handleItemClick(profileItem));
// Note: settingsItem won't fire events when disabled

// Create navigation container
const navList = document.createElement('div');
navList.appendChild(homeItem);
navList.appendChild(profileItem);
navList.appendChild(settingsItem);

document.body.appendChild(navList);

Usage Patterns

List Organization Patterns

Implement List Item for structured content presentation:

Navigation Lists - Menu items, breadcrumbs, and hierarchical navigation
Content Lists - Article lists, product catalogs, and information directories
Action Lists - Operation menus, quick actions, and task management
Status Lists - System monitoring, progress tracking, and state indicators

Interactive Behavior Patterns

Enhance user interaction through effective List Item implementation: - Selection States - Single and multi-select list behaviors - Action Integration - Click handlers, navigation, and operation triggers - Drag and Drop - Reorderable lists and item manipulation - Contextual Actions - Right-click menus and inline action buttons

Content Structure Patterns

Organize List Item content for optimal information presentation: - Primary Content - Main item information with clear hierarchy - Secondary Details - Supporting information and metadata display - Visual Indicators - Icons, badges, and status indicators - Responsive Layout - Adaptive content arrangement across screen sizes

Ensure inclusive List Item experiences: - Keyboard Navigation - Arrow key navigation and enter/space activation - Screen Reader Support - Proper labeling and list structure semantics - Focus Management - Clear focus indicators and logical tab order - Touch Optimization - Adequate touch targets and gesture support

Common Use Cases

Sidebar navigation menus
Breadcrumb navigation components
Multi-level menu hierarchies

Content Management

File and document listings
User and contact directories
Product and inventory catalogs

System Interfaces

Settings and configuration lists
Notification and alert displays
Task and workflow management

Troubleshooting

Common Issues

Click Events Not Triggering

Problem: List item click events don't fire or respond to user interactions

Solution:

Verify event listeners are properly attached and item is not disabled, check for overlapping elements blocking clicks

Selection State Not Updating

Problem: Selected state doesn't change visually when item is clicked

Solution:

Ensure selected property is being updated correctly and parent component state management is working properly

Icons Not Displaying

Problem: List item icons don't appear or show as broken images

Solution:

Verify icon names are correct and icon library is properly imported, check network requests for missing icon assets

Disabled Items Still Interactive

Problem: Disabled list items still respond to clicks or show hover states

Solution:

Check disabled property is set correctly and CSS styles are applying proper disabled state styling

Implementation Support

Flexible Content Architecture - Comprehensive slot-based system supporting custom icons, labels, and complex content structures with consistent styling
Container Coordination - Automatic integration with parent menu and navigation components for unified keyboard navigation and selection management
Accessibility Integration - Built-in focus management, ARIA attributes, and keyboard navigation support for inclusive user interface design

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.

List Item Component

Overview

Core Capabilities

Basic Implementation

Usage Patterns

List Organization Patterns

Interactive Behavior Patterns

Content Structure Patterns

Accessibility and Navigation Patterns

Common Use Cases

Navigation Interfaces

Content Management

System Interfaces

Troubleshooting

Common Issues

Click Events Not Triggering

Selection State Not Updating

Icons Not Displaying

Disabled Items Still Interactive

Implementation Support

Resources

Storybook Documentation