Skip to content

Pending Review

Pending Review from User Experience (UX)

Form Expander Component

Overview

The PWC Form Expander component provides collapsible sections for forms, allowing users to show and hide optional or advanced form fields. Built with Lit web components, it offers smooth expand/collapse functionality with customizable labels and disabled states for progressive disclosure patterns.

Core Capabilities

  • Progressive Disclosure - Hide and reveal form sections to reduce cognitive load and improve form completion rates
  • Customizable Labels - Configurable expand and collapse button text to match specific form context and user expectations
  • Visual Feedback - Clear chevron icons indicating current state with smooth transitions between expanded and collapsed views
  • Disabled State - Support for disabled expanders that prevent interaction when form sections are not available
  • Form Integration - Seamless integration with form sections and form inputs for consistent layout and behavior
  • Keyboard Accessibility - Full keyboard navigation support with proper focus management and screen reader compatibility

When to use Form Expander:

  • Optional form sections that aren't required for basic form completion but provide additional configuration options
  • Advanced settings and preferences that power users need but shouldn't overwhelm typical users
  • Conditional form fields that appear based on previous selections or user preferences
  • Complex forms with multiple categories where showing all fields simultaneously would create information overload

When not to use Form Expander:

  • Required form fields that users must complete - these should always be visible and accessible
  • Single field additions where the expander adds more complexity than value to the user experience
  • Navigation between different form pages where routing and multi-step patterns are more appropriate

Basic Implementation

import { PwcFormExpander, PwcInput } from "@progress-i360/pwc-react";

function MyComponent() {
  return (
    <>
      <PwcInput name="firstName" placeholder="First Name" />
      <PwcInput name="lastName" placeholder="Last Name" />

      <PwcFormExpander
        expandLabel="Show additional name fields"
        collapseLabel="Hide additional fields">
        <PwcInput name="middleName" label="Middle Name" />
        <PwcInput name="suffix" label="Suffix" />
      </PwcFormExpander>
    </>
  );
}

import '@progress-i360/progress-web-components/checkbox';
import '@progress-i360/progress-web-components/form-expander';
import '@progress-i360/progress-web-components/input';

function NotificationPreferences() {
  return (
    <>
      <pwc-input type="email" name="email" label="Email Address" required></pwc-input>

      <pwc-form-expander
        expand-label="Notification preferences"
        collapse-label="Hide notification settings"
      >
        <pwc-checkbox name="email-alerts" label="Email alerts"></pwc-checkbox>
        <pwc-checkbox name="sms-notifications" label="SMS notifications"></pwc-checkbox>
      </pwc-form-expander>
    </>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@progress-i360/progress-web-components/body";
import "@progress-i360/progress-web-components/button";
import "@progress-i360/progress-web-components/button-group";
import "@progress-i360/progress-web-components/checkbox";
import "@progress-i360/progress-web-components/flex";
import "@progress-i360/progress-web-components/form-expander";
import "@progress-i360/progress-web-components/form-section";
import "@progress-i360/progress-web-components/heading";
import "@progress-i360/progress-web-components/input";

@Component({
  selector: 'form-expander-demo',
  template: `
    <pwc-flex direction="column" gap="m" padding="m">
      <pwc-heading content="Registration Form" size="l"></pwc-heading>

      <pwc-flex direction="column" gap="l">
        <!-- Required Fields -->
        <pwc-form-section heading="Required Information">
          <pwc-input name="name" label="Full Name" [required]="true" autoFocus></pwc-input>
          <pwc-input name="email" label="Email Address" type="email" [required]="true"></pwc-input>
        </pwc-form-section>

        <!-- Optional Advanced Settings -->
        <pwc-form-expander 
          expand-label="Show advanced options"
          collapse-label="Hide advanced options">

          <pwc-input name="company" label="Company Name"></pwc-input>
          <pwc-input name="website" label="Website URL" type="url"></pwc-input>
          <pwc-checkbox name="marketing" label="Receive marketing emails"></pwc-checkbox>
        </pwc-form-expander>

        <!-- Optional Contact Preferences -->
        <pwc-form-expander 
          expand-label="Show contact preferences"
          collapse-label="Hide contact preferences">

          <pwc-input name="phone" label="Phone Number" type="tel"></pwc-input>
          <pwc-button-group 
            name="contact_method" 
            label="Preferred Contact Method"
            [options]="contactOptions">
          </pwc-button-group>
        </pwc-form-expander>
      </pwc-flex>

      <pwc-flex gap="s">
        <pwc-button label="Submit Registration" variant="primary" (pwc-click)="submitForm()"></pwc-button>
        <pwc-button label="Reset Form" variant="outline" (pwc-click)="resetForm()"></pwc-button>
      </pwc-flex>

      <pwc-body [content]="getStatusText()" color="subtle" size="xs"></pwc-body>
    </pwc-flex>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class FormExpanderDemo {
  submissionCount = 0;
  resetCount = 0;

  contactOptions = [
    { label: 'Email', value: 'email' },
    { label: 'Phone', value: 'phone' },
    { label: 'SMS', value: 'sms' }
  ];

  submitForm() {
    this.submissionCount++;
    // Simulate form submission success
  }

  resetForm() {
    this.resetCount++;
  }

  getStatusText() {
    return `Submissions: ${this.submissionCount}, Resets: ${this.resetCount}`;
  }
}

import '@progress-i360/progress-web-components/form-expander';
import '@progress-i360/progress-web-components/input';

const expander = document.createElement('pwc-form-expander');
expander.setAttribute('expand-label', 'Show advanced options');
expander.setAttribute('collapse-label', 'Hide advanced options');

const advancedInput = document.createElement('pwc-input');
advancedInput.setAttribute('label', 'Advanced Setting');
expander.appendChild(advancedInput);

document.body.appendChild(expander);

Usage Patterns

  • Optional Information - Collect additional user details that aren't required but provide value for personalization and enhanced functionality
  • Advanced Settings - Provide power user configurations and technical options without overwhelming basic users with complex choices
  • Conditional Fields - Show relevant form fields based on previous selections while keeping the main form clean and focused
  • Grouped Extensions - Organize related optional fields into logical sections that users can expand when needed

Best Practices

Content Strategy Guidelines

  • Clear Action Labels - Use descriptive expand/collapse labels that clearly indicate what content will be revealed or hidden
  • Logical Grouping - Group related optional fields together so users can make informed decisions about expanding sections
  • Progressive Complexity - Place basic required fields first, then use expanders for advanced or optional configurations
  • Contextual Relevance - Only include optional sections that provide genuine value rather than adding complexity for completeness

Performance Optimization

  • Lazy Rendering - Consider lazy loading complex form fields within expanders until they're actually expanded
  • State Management - Efficiently manage expanded state to prevent unnecessary re-renders of collapsed content
  • Animation Performance - Use CSS transitions for smooth expand/collapse animations without JavaScript overhead
  • Memory Cleanup - Properly dispose of event listeners and form field subscriptions when expanders are removed

Integration Architecture

  • Form Context Integration - Ensure expanded form fields properly integrate with parent form validation and submission
  • Accessibility Standards - Implement proper ARIA attributes for expandable content and keyboard navigation
  • Consistent Styling - Use design system tokens for consistent spacing, colors, and typography within expanded sections
  • Responsive Design - Ensure expanders work appropriately across different screen sizes and form layouts

Common Use Cases

User Profile Forms

  • Personal information expanders for optional fields like middle names, titles, and demographic information
  • Privacy settings sections with visibility preferences and communication options
  • Professional details including job titles, company information, and industry categories

Account Settings

  • Security options including two-factor authentication setup and backup recovery methods
  • Notification preferences with granular control over email, SMS, and in-app notifications
  • Advanced configuration options for API access, integrations, and developer settings

Registration Forms

  • Optional contact information including phone numbers, addresses, and social media profiles
  • Preference sections for marketing communications, newsletter subscriptions, and content interests
  • Accessibility options including language preferences, display settings, and assistive technology support

Troubleshooting

Common Issues

Actions Not Triggering

Symptoms: Expand/collapse buttons don't respond to clicks or keyboard activation

Solutions:

  • Verify button is not disabled and form expander has proper event handlers

  • Check that focus styling is properly applied and button receives keyboard focus

  • Ensure click events aren't being prevented by parent elements or conflicting handlers

Actions Not Visible

Symptoms: Expander content doesn't show/hide or appears with incorrect layout

Solutions:

  • Confirm expanded property is properly bound and managed in component state

  • Check CSS display properties and transitions aren't conflicting with expand/collapse animations

  • Verify slot content is properly rendered within the expanded section container

Layout Issues

Symptoms: Expanded content appears misaligned or with incorrect spacing relative to other form elements

Solutions:

  • Use consistent gap and padding values that match other form sections and components

  • Check parent container flex properties don't conflict with expander layout requirements

  • Ensure form fields within expander use same layout patterns as main form fields

Icon Problems

Symptoms: Chevron icons don't appear or don't rotate properly during expand/collapse transitions

Solutions:

  • Verify icon system is loaded and chevron-up/chevron-down icons are available

  • Check icon color matches link styling and maintains proper contrast for accessibility

  • Ensure icon transitions are smooth and provide clear visual feedback for state changes

Implementation Support

  • Form Architecture - Integration patterns for complex forms with multiple expandable sections and conditional logic
  • State Management - Best practices for managing expander state across form submissions and validation cycles
  • Accessibility Compliance - WCAG implementation for expandable content including proper ARIA labeling and keyboard support

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.