Pending Review

Pending Review from User Experience (UX)

Wizard Component

Overview

The PWC Wizard component provides a multi-step form interface with progressive navigation, step validation, and dynamic content management. Built with comprehensive form integration, visual progress indicators, and flexible step configuration, it guides users through complex workflows by breaking them into manageable sections with clear progress tracking and seamless data persistence across steps.

Core Capabilities

Multi-Step Navigation - Sequential form progression with back/forward controls and dynamic step management for complex data collection workflows
Visual Progress Indicators - Step counter with completion status, progress visualization, and responsive step label management
Dynamic Content Loading - Flexible step content with onShow callbacks for dynamic form section generation and conditional step configuration
Form Data Persistence - Automatic data preservation across steps with validation state management and seamless data synchronization
Step Validation Integration - Individual step validation with submit callbacks and error handling for robust workflow management
Responsive Design - Mobile-optimized step indicators with adaptive label display and responsive form layout management

When to use Wizard:

Complex multi-step processes requiring sequential data collection such as registration, onboarding, or configuration workflows
Data entry scenarios where breaking information into logical steps improves user experience and completion rates
Progressive disclosure patterns where later steps depend on earlier choices and require conditional form generation
Long forms that benefit from step-by-step guidance with progress tracking and the ability to review and edit previous steps

When not to use Wizard:

Simple forms where single-page layouts provide better user experience without unnecessary navigation complexity
Non-sequential processes where steps can be completed in any order and don't require progressive data dependency
Quick data entry scenarios where wizard overhead creates friction rather than improving user workflow efficiency

Basic Implementation

React 18React 19+AngularPure JavaScript

import { PwcRoot, PwcWizard } from "@progress-i360/pwc-react";

const steps = [
  { label: "Step 1", onShow: (args) => args.success() },
  { label: "Step 2", onShow: (args) => args.success() }
];

function App() {
  return (
    <PwcRoot assetPath="/pwc/assets">
      <SimpleWizard />
    </PwcRoot>
  );
}

function SimpleWizard() {
  return (
    <PwcWizard
      heading="Setup Wizard"
      steps={steps}
    />
  );
}

export default App;

import { useEffect, useMemo, useRef } from "react";
import "@progress-i360/progress-web-components/root";
import "@progress-i360/progress-web-components/wizard";

function App() {
  const wizardRef = useRef<HTMLElement | null>(null);
  const steps = useMemo(
    () => [
      { label: "Basic Info", onShow: (args: any) => args.success() },
      { label: "Configuration", onShow: (args: any) => args.success() },
      { label: "Review", onShow: (args: any) => args.success() }
    ],
    []
  );

  useEffect(() => {
    if (wizardRef.current) {
      (wizardRef.current as any).steps = steps;
    }
  }, [steps]);

  return (
    <>
      <pwc-root asset-path="/pwc/assets"></pwc-root>
      <pwc-wizard
        ref={wizardRef}
        heading="Project Setup"
      ></pwc-wizard>
    </>
  );
}

export default App;

// component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@progress-i360/progress-web-components/root";
import "@progress-i360/progress-web-components/button";
import "@progress-i360/progress-web-components/checkbox";
import "@progress-i360/progress-web-components/form-expander";
import "@progress-i360/progress-web-components/form-section";
import "@progress-i360/progress-web-components/input";
import "@progress-i360/progress-web-components/notice";
import "@progress-i360/progress-web-components/progress-bar";
import "@progress-i360/progress-web-components/radio";
import "@progress-i360/progress-web-components/radio-section";
import "@progress-i360/progress-web-components/select";
import "@progress-i360/progress-web-components/wizard";

@Component({
  selector: 'wizard-demo',
  template: `
    <pwc-root asset-path="/pwc/assets"></pwc-root>
    <pwc-wizard 
      [currentStep]="currentStep"
      [totalSteps]="totalSteps"
      (pwc-wizard-change)="handleStepChange($event)">

      <!-- Step 1: User Information -->
      <div slot="step" *ngIf="currentStep === 1">
        <pwc-form-section heading="User Information" subheading="Tell us about yourself">
          <pwc-form-expander title="Personal Details" [isRequired]="true">
            <pwc-input 
              label="Full Name" 
              [value]="formData.fullName"
              [isRequired]="true"
              (pwc-change)="updateField('fullName', $event)">
            </pwc-input>
            <pwc-input 
              label="Email" 
              type="email"
              [value]="formData.email"
              [isRequired]="true"
              (pwc-change)="updateField('email', $event)">
            </pwc-input>
            <pwc-select 
              label="Department"
              [value]="formData.department"
              [isRequired]="true"
              (pwc-change)="updateField('department', $event)">
              <option value="">Select Department</option>
              <option value="engineering">Engineering</option>
              <option value="marketing">Marketing</option>
              <option value="sales">Sales</option>
              <option value="support">Support</option>
            </pwc-select>
          </pwc-form-expander>
        </pwc-form-section>
      </div>

      <!-- Step 2: Preferences -->
      <div slot="step" *ngIf="currentStep === 2">
        <pwc-form-section heading="Preferences" subheading="Customize your experience">
          <pwc-form-expander title="Notification Settings" [isRequired]="false">
            <pwc-checkbox 
              label="Email notifications"
              [value]="formData.emailNotifications"
              (pwc-change)="updateField('emailNotifications', $event)">
            </pwc-checkbox>
            <pwc-checkbox 
              label="SMS notifications"
              [value]="formData.smsNotifications"
              (pwc-change)="updateField('smsNotifications', $event)">
            </pwc-checkbox>
            <pwc-radio-section 
              heading="Notification Frequency"
              name="frequency"
              [value]="formData.frequency"
              (pwc-change)="updateField('frequency', $event)">
              <pwc-radio value="immediate" label="Immediate"></pwc-radio>
              <pwc-radio value="daily" label="Daily digest"></pwc-radio>
              <pwc-radio value="weekly" label="Weekly summary"></pwc-radio>
            </pwc-radio-section>
          </pwc-form-expander>
        </pwc-form-section>
      </div>

      <!-- Step 3: Review -->
      <div slot="step" *ngIf="currentStep === 3">
        <pwc-form-section heading="Review & Confirm" subheading="Please review your information">
          <pwc-form-expander title="Summary" [isRequired]="false">
            <div class="review-content">
              <p><strong>Name:</strong> {{ formData.fullName || 'Not provided' }}</p>
              <p><strong>Email:</strong> {{ formData.email || 'Not provided' }}</p>
              <p><strong>Department:</strong> {{ formData.department || 'Not selected' }}</p>
              <p><strong>Email Notifications:</strong> {{ formData.emailNotifications ? 'Enabled' : 'Disabled' }}</p>
              <p><strong>SMS Notifications:</strong> {{ formData.smsNotifications ? 'Enabled' : 'Disabled' }}</p>
              <p><strong>Frequency:</strong> {{ getFrequencyLabel() }}</p>
            </div>
            <pwc-notice 
              variant="tip" 
              message="You can modify these settings anytime in your profile."
              [dismissible]="false">
            </pwc-notice>
          </pwc-form-expander>
        </pwc-form-section>
      </div>

      <!-- Step Navigation -->
      <div slot="actions">
        <pwc-button 
          label="Previous" 
          variant="outline" 
          [disabled]="currentStep === 1"
          (pwc-click)="previousStep()">
        </pwc-button>
        <pwc-button 
          *ngIf="currentStep < totalSteps"
          label="Next" 
          variant="primary"
          [disabled]="!isCurrentStepValid()"
          (pwc-click)="nextStep()">
        </pwc-button>
        <pwc-button 
          *ngIf="currentStep === totalSteps"
          label="Complete Setup" 
          variant="primary"
          [disabled]="!isFormValid()"
          (pwc-click)="completeWizard()">
        </pwc-button>
      </div>
    </pwc-wizard>

    <div class="wizard-status">
      <pwc-progress-bar 
        [value]="(currentStep / totalSteps) * 100"
        [showPercentage]="true">
      </pwc-progress-bar>
      <p>Step {{ currentStep }} of {{ totalSteps }}: {{ getCurrentStepTitle() }}</p>
    </div>

    <div class="completion-message" *ngIf="isCompleted">
      <pwc-notice 
        variant="success" 
        heading="Setup Complete!" 
        message="Your account has been configured successfully."
        [dismissible]="false">
      </pwc-notice>
      <pwc-button 
        label="Start Over" 
        variant="outline" 
        (pwc-click)="resetWizard()">
      </pwc-button>
    </div>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class WizardDemo {
  currentStep = 1;
  totalSteps = 3;
  isCompleted = false;

  formData = {
    fullName: '',
    email: '',
    department: '',
    emailNotifications: false,
    smsNotifications: false,
    frequency: 'daily'
  };

  stepTitles = {
    1: 'User Information',
    2: 'Preferences',
    3: 'Review & Confirm'
  };

  handleStepChange(e: Event) {
    const detail = (e as CustomEvent).detail;
    this.currentStep = detail.step;
  }

  updateField(fieldName: string, e: Event) {
    const detail = (e as CustomEvent).detail;
    (this.formData as any)[fieldName] = detail.value;
  }

  nextStep() {
    if (this.currentStep < this.totalSteps && this.isCurrentStepValid()) {
      this.currentStep++;
    }
  }

  previousStep() {
    if (this.currentStep > 1) {
      this.currentStep--;
    }
  }

  isCurrentStepValid(): boolean {
    switch (this.currentStep) {
      case 1:
        return !!(this.formData.fullName && this.formData.email && this.formData.department);
      case 2:
        return true; // Preferences are optional
      case 3:
        return this.isFormValid();
      default:
        return false;
    }
  }

  isFormValid(): boolean {
    return !!(
      this.formData.fullName &&
      this.formData.email &&
      this.formData.department
    );
  }

  getCurrentStepTitle(): string {
    return this.stepTitles[this.currentStep as keyof typeof this.stepTitles] || '';
  }

  getFrequencyLabel(): string {
    const labels = {
      immediate: 'Immediate',
      daily: 'Daily digest',
      weekly: 'Weekly summary'
    };
    return labels[this.formData.frequency as keyof typeof labels] || 'Not selected';
  }

  completeWizard() {
    if (this.isFormValid()) {
      console.log('Wizard completed with data:', this.formData);
      this.isCompleted = true;
    }
  }

  resetWizard() {
    this.currentStep = 1;
    this.isCompleted = false;
    this.formData = {
      fullName: '',
      email: '',
      department: '',
      emailNotifications: false,
      smsNotifications: false,
      frequency: 'daily'
    };
  }
}

import "@progress-i360/progress-web-components/root";
import "@progress-i360/progress-web-components/wizard";

const root = document.createElement('pwc-root');
root.setAttribute('asset-path', '/pwc/assets');
document.body.appendChild(root);

// Create a simple 3-step wizard
const wizard = document.createElement('pwc-wizard');
wizard.setAttribute('heading', 'User Registration');
wizard.setAttribute('hint', 'Complete all steps to create your account');

// Define wizard steps
const steps = [
  {
    label: 'Personal Info',
    onShow: (args) => args.success(),
    onSubmit: (args) => args.success()
  },
  {
    label: 'Contact Details', 
    onShow: (args) => args.success(),
    onSubmit: (args) => args.success()
  },
  {
    label: 'Review',
    onShow: (args) => args.success(),
    onSubmit: (args) => args.success()
  }
];
wizard.steps = steps;

// Handle wizard completion
wizard.addEventListener('pwc-wizard-change', (event) => {
  console.log('Step changed:', event.detail);
});

// Add to page
document.body.appendChild(wizard);

Usage Patterns

Multi-Step Registration - User account creation with progressive data collection and validation across multiple logical sections
Configuration Wizards - System setup processes that guide users through complex configuration options with step-by-step progression
Onboarding Workflows - New user introduction processes with sequential information gathering and preference setting
Data Import Processes - Complex data migration or import workflows requiring validation and confirmation at each stage

Best Practices

Content Strategy Guidelines

Logical Step Progression - Organize steps in natural workflow order that matches user mental models and reduces cognitive load
Clear Step Labels - Use descriptive step names and helpful hints that clearly indicate the purpose and content of each step
Progress Communication - Provide clear progress indicators and step completion feedback to maintain user confidence and motivation
Error Handling Strategy - Implement comprehensive error messaging with specific guidance for resolving validation issues at each step

Performance Optimization

Dynamic Content Loading - Use onShow callbacks efficiently to load step content only when needed and avoid unnecessary rendering
Form Data Management - Implement efficient data persistence patterns that minimize memory usage while maintaining state across steps
Validation Optimization - Use step-level validation to prevent unnecessary processing and provide immediate feedback to users
Responsive Design Handling - Optimize step indicator layout and content presentation for different screen sizes and device orientations

Integration Architecture

Form Context Integration - Coordinate seamlessly with PWC form systems for validation, error handling, and data management workflows
Step Lifecycle Management - Implement proper step initialization, validation, and cleanup patterns for robust wizard functionality
Error Recovery Patterns - Design error handling workflows that allow users to correct issues and continue without losing progress
Data Validation Strategies - Implement both client-side and server-side validation patterns with appropriate error messaging and recovery options

Common Use Cases

Data Table Headers

User registration wizards with account creation, profile setup, and preference configuration for comprehensive onboarding
Product configuration wizards with specification selection, customization options, and pricing calculation for complex products
Data import wizards with file selection, mapping configuration, and validation confirmation for database migration processes

Search Result Sections

Advanced search configuration wizards with filter setup, criteria definition, and result customization for complex query building
Report generation wizards with data source selection, parameter configuration, and output format selection for business intelligence
Export configuration wizards with data selection, format options, and delivery preferences for data extraction workflows

Dashboard customization wizards with widget selection, layout configuration, and preference settings for personalized interfaces
System integration wizards with service connection, authentication setup, and configuration validation for external system connections
Backup configuration wizards with schedule setup, retention policies, and destination configuration for data protection workflows

Troubleshooting

Common Issues

Actions Not Triggering

Symptoms: Navigation buttons don't work, step progression fails, or onSubmit callbacks don't execute properly

Solutions:

Verify that step callback functions (onShow, onSubmit) are properly defined and return appropriate success/failure responses
Check that form validation states are managed correctly and don't prevent step progression when data is valid
Ensure that async operations in step callbacks handle promises properly with appropriate error handling and state management

Actions Not Visible

Symptoms: Steps don't render content, navigation controls missing, or progress indicators don't display properly

Solutions:

Confirm that step content generation works correctly through onShow callbacks with proper FormSectionProps or template returns
Check that wizard component styling and layout accommodate different content types and responsive design requirements
Verify that step indicator rendering handles different step states (current, completed, disabled) with appropriate visual feedback

Layout Issues

Symptoms: Wizard appears with incorrect dimensions, content overflow, or responsive behavior problems

Solutions:

Use appropriate container sizing and max-height calculations to ensure wizard fits within viewport constraints
Check that step content layouts work correctly with different content lengths and form field configurations
Ensure that responsive step label management works properly on different screen sizes with appropriate hiding/showing logic

Icon Problems

Symptoms: Step progress icons don't display, incorrect icons shown for step states, or icon colors don't match theme

Solutions:

Verify that progress indicator icons (checkmark-outline, circle-dash, port-input) are available in your icon system
Check that step state logic properly determines which icons to display based on current step position and completion status
Ensure that icon color theming works correctly with step states (success, info, subtler) and matches overall design system

Implementation Support

Multi-Step Workflow Design - Best practices for designing intuitive wizard flows with appropriate step granularity and progression logic
Form Integration Strategies - Comprehensive guidance for integrating wizard components with PWC form systems and validation workflows
Step Content Management - Patterns for dynamic content generation, conditional step logic, and complex form section coordination

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.

Wizard 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

Storybook Documentation