Skip to content

Pending Review

Pending Review from User Experience (UX)

Placeholder Component

Overview

The PWC Placeholder is an empty state component in the Progress Web Components design system. It provides consistent messaging and visual feedback when no data is available, helping users understand empty states and offering actionable next steps across React and Angular applications.

Core Capabilities

  • Empty State Messaging - Clear, informative messages for when no data is available or found
  • Visual Icon Support - Customizable icons to reinforce the empty state context and meaning
  • Action Button Integration - Optional action buttons to guide users toward resolving empty states
  • Flexible Content - Customizable headings, descriptions, and visual elements for different scenarios
  • Responsive Layout - Centered, adaptive design that works across desktop and mobile interfaces
  • Internationalization Ready - Built-in localization support for multi-language applications

When to use Placeholder:

  • Display empty states for data tables, search results, or content lists
  • Show "no results found" messages with helpful guidance for users
  • Provide visual feedback when content is unavailable or hasn't been created yet
  • Guide users with actionable buttons to create or import initial content

When not to use Placeholder:

  • Loading states during data fetching operations (use loading skeletons instead)
  • Error states or system failures (use error components instead)
  • Navigation or structural elements that aren't content-related

Basic Implementation

import React from 'react';
import { PwcPlaceholder, PwcButton } from "@progress-i360/pwc-react";

function MyComponent() {
  const handleCreateItem = () => {
    console.log('Create new item');
  };

  return (
      <PwcPlaceholder 
        heading="No Users Found"
        description="There are no users in your organization yet."
        icon="user-plus"
        iconColor="primary"
      >
        <PwcButton 
          variant="primary" 
          label="Add First User"
          onClick={handleCreateItem}
        />
        <PwcButton 
          variant="outline" 
          label="Import Users"
        />
      </PwcPlaceholder>
  );
}

import { useCallback } from 'react';
import '@progress-i360/progress-web-components/placeholder';
import '@progress-i360/progress-web-components/button';

function MyComponent() {
  const handleCreate = useCallback(() => {
    console.log('Create clicked');
  }, []);

  return (
      <pwc-placeholder 
        heading="No Data Available"
        description="Start by creating your first item."
        icon="folder-open"
        iconColor="subtle"
      >
        <pwc-button 
          variant="primary" 
          label="Create Item"
          onPwcClick={handleCreate}
        ></pwc-button>
      </pwc-placeholder>
  );
}

// component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@progress-i360/progress-web-components/placeholder';
import '@progress-i360/progress-web-components/button';

@Component({
  selector: 'placeholder-demo',
  template: `
    <pwc-placeholder 
      [heading]="heading"
      [description]="message"
      icon="search">
      <pwc-button 
        variant="primary" 
        label="Try Again"
        (pwc-click)="refresh()">
      </pwc-button>
    </pwc-placeholder>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class PlaceholderDemo {
  heading = 'No Results Found';
  message = 'Try adjusting your search criteria.';

  refresh() {
    this.heading = 'Refreshing...';
    this.message = 'Please wait while we search for results.';

    setTimeout(() => {
      this.heading = 'Still No Results';
      this.message = 'You might want to try different search terms.';
    }, 2000);
  }
}

// Create placeholder element
const placeholder = document.createElement('pwc-placeholder');
placeholder.heading = 'No Data Found';
placeholder.description = 'There are no items to display.';
placeholder.icon = 'folder-open';

// Update placeholder content function
function updatePlaceholder(newHeading) {
  placeholder.heading = newHeading;
}

// Example usage and dynamic content updates
updatePlaceholder('Search Results Empty');
document.body.appendChild(placeholder);

Usage Patterns

Placeholder components adapt to different empty state scenarios:

  • No Data States - Display when collections, tables, or lists have no items to show
  • Search No Results - Show when search queries return no matching results with filter suggestions
  • Feature Empty States - Guide users to start using features they haven't explored yet
  • Content Creation Prompts - Encourage users to create their first content items with clear calls-to-action

Best Practices

Content Strategy Guidelines

  • Clear Messaging - Use specific, helpful language that explains why content is empty
  • Actionable Solutions - Provide buttons or links that help users resolve the empty state
  • Appropriate Icons - Choose icons that reinforce the context and meaning of the empty state
  • Consistent Tone - Maintain friendly, encouraging language rather than negative messaging

Performance Optimization

  • Lazy Icon Loading - Load placeholder icons only when components are rendered
  • Button Optimization - Render action buttons conditionally based on user permissions
  • Content Caching - Cache placeholder text and icons for repeated empty state displays
  • Efficient Re-renders - Update placeholder content only when necessary to minimize performance impact

Integration Architecture

  • State Coordination - Connect placeholder display to actual data loading and filtering states
  • Action Integration - Ensure placeholder actions properly integrate with application workflows
  • Responsive Design - Test placeholder layouts across different screen sizes and orientations
  • Accessibility Standards - Implement proper ARIA labels and screen reader support

Common Use Cases

Data Table Empty States

  • Display when tables have no rows due to filters or empty datasets
  • Provide actions to clear filters or add initial data entries
  • Show contextual icons that match the type of data expected

Search Result Placeholders

  • Appear when search queries return no matching results or items
  • Offer suggestions to modify search terms or clear active filters
  • Include options to broaden search criteria or browse all items

Dashboard Widget Empty States

  • Show when dashboard widgets have no data to display or visualize
  • Provide setup actions to configure data sources or import content
  • Display helpful guidance for first-time users setting up dashboards

Troubleshooting

Common Issues

Icons Not Displaying

Problem: Placeholder icons don't appear or show as broken images
Solution:

  • Verify icon names are correct and icon library is properly imported and configured

Action Buttons Not Working

Problem: Placeholder action buttons don't respond to clicks or events
Solution:

  • Check that event listeners are properly attached and button states aren't disabled

Layout Alignment Issues

Problem: Placeholder content appears misaligned or doesn't center properly
Solution:

  • Review container styles and ensure proper flex layout configuration

Text Localization Problems

Problem: Placeholder text doesn't update for different locales or languages
Solution:

  • Verify localization setup and ensure proper message key mapping

Implementation Support

For detailed implementation guidance:

  • API Documentation - Complete component props and styling options in Storybook
  • Interactive Examples - Live demos showing different empty state scenarios and configurations
  • Content Guidelines - Best practices for writing effective placeholder messaging and calls-to-action

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.