Form Ux Patterns

{
  "name": "form-ux-patterns",
  "description": "UX patterns for complex forms including multi-step wizards, cognitive chunking, progressive disclosure, and conditional fields. Use when building checkout flows, onboarding wizards, or forms with many fields.",
  "tags": [
    "forms",
    "ui-design",
    "code-generation"
  ],
  "sub_skills": [],
  "source": "claude-user",
  "type": "template",
  "depends_on": [],
  "enhances": [
    "form-react",
    "form-vue",
    "form-vanilla"
  ],
  "last_reviewed_at": "2026-06-08",
  "review_score": 66,
  "relevance_tier": "B"
}

/**
 * Multi-Step Form Component
 * 
 * React component for wizard-style multi-step forms with:
 * - Per-step validation
 * - Step indicator/progress
 * - Focus management on step change
 * - Form chunking (5-7 fields per step)
 * 
 * @module multi-step-form
 */

import React, {
  createContext,
  useContext,
  useState,
  useCallback,
  ReactNode,
  ComponentType
} from 'react';
import { useForm, FormProvider, UseFormReturn, FieldValues } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// =============================================================================
// TYPES
// =============================================================================

/**
 * Form chunk definition (5-7 fields max per step)
 */
export interface FormChunk {
  /** Unique step identifier */
  id: string;
  
  /** Step title (shown in indicator) */
  title: string;
  
  /** Step description (briefing, separate from field labels) */
  description?: string;
  
  /** Field names included in this step */
  fields: string[];
  
  /** Zod schema for this step's fields */
  schema: z.ZodType;
  
  /** Optional: Skip this step based on form values */
  skipIf?: (values: FieldValues) => boolean;
  
  /** Optional: Custom step component */
  component?: ComponentType<StepProps>;
}

export interface StepProps {
  /** Step configuration */
  step: FormChunk;
  
  /** Step index (0-based) */
  index: number;
  
  /** Total number of steps */
  total: number;
  
  /** Whether this is the active step */
  isActive: boolean;
}

export interface MultiStepFormProps<T extends FieldValues> {
  /** Step definitions */
  steps: FormChunk[];
  
  /** Combined schema for full form validation */
  schema: z.ZodType<T>;
  
  /** Form submission handler */
  onSubmit: (data: T) => Promise<void> | void;
  
  /** Initial form values */
  defaultValues?: Partial<T>;
  
  /** Children render function or components */
  children: ReactNode | ((props: MultiStepRenderProps<T>) => ReactNode);
  
  /** Show step indicator */
  showIndicator?: boolean;
  
  /** Custom submit button text */
  submitLabel?: string;
  
  /** Custom next button text */
  nextLabel?: string;
  
  /** Custom back button text */
  backLabel?: string;
}

export interface MultiStepRenderProps<T extends FieldValues> {
  /** Current step index */
  currentStep: number;
  
  /** Total steps count */
  totalSteps: number;
  
  /** Current step config */
  step: FormChunk;
  
  /** Go to next step (validates current) */
  next: () => Promise<boolean>;
  
  /** Go to previous step */
  back: () => void;
  
  /** Go to specific step */
  goTo: (step: number) => void;
  
  /** Whether on first step */
  isFirst: boolean;
  
  /** Whether on last step */
  isLast: boolean;
  
  /** Form methods from react-hook-form */
  form: UseFormReturn<T>;
  
  /** Submit the form */
  submit: () => void;
}

// =============================================================================
// CONTEXT
// =============================================================================

interface MultiStepContextValue {
  currentStep: number;
  totalSteps: number;
  goTo: (step: number) => void;
  next: () => Promise<boolean>;
  back: () => void;
}

const MultiStepContext = createContext<MultiStepContextValue | null>(null);

/**
 * Hook to access multi-step form context
 */
export function useMultiStep() {
  const context = useContext(MultiStepContext);
  if (!context) {
    throw new Error('useMultiStep must be used within MultiStepForm');
  }
  return context;
}

// =============================================================================
// STEP INDICATOR
// =============================================================================

interface StepIndicatorProps {
  steps: FormChunk[];
  currentStep: number;
  onStepClick?: (step: number) => void;
  allowNavigation?: boolean;
}

/**
 * Visual step indicator/progress bar
 */
export function StepIndicator({
  steps,
  currentStep,
  onStepClick,
  allowNavigation = false
}: StepIndicatorProps) {
  return (
    <nav aria-label="Form progress" className="step-indicator">
      <ol className="step-indicator__list">
        {steps.map((step, index) => {
          const isComplete = index < currentStep;
          const isCurrent = index === currentStep;
          const isClickable = allowNavigation && index < currentStep;
          
          return (
            <li
              key={step.id}
              className={`step-indicator__item ${isComplete ? 'complete' : ''} ${isCurrent ? 'current' : ''}`}
            >
              {isClickable ? (
                <button
                  type="button"
                  onClick={() => onStepClick?.(index)}
                  className="step-indicator__button"
                  aria-current={isCurrent ? 'step' : undefined}
                >
                  <span className="step-indicator__number">{index + 1}</span>
                  <span className="step-indicator__title">{step.title}</span>
                </button>
              ) : (
                <span
                  className="step-indicator__content"
                  aria-current={isCurrent ? 'step' : undefined}
                >
                  <span className="step-indicator__number">
                    {isComplete ? '✓' : index + 1}
                  </span>
                  <span className="step-indicator__title">{step.title}</span>
                </span>
              )}
              
              {index < steps.length - 1 && (
                <span className="step-indicator__connector" aria-hidden="true" />
              )}
            </li>
          );
        })}
      </ol>
      
      <div className="sr-only" aria-live="polite">
        Step {currentStep + 1} of {steps.length}: {steps[currentStep]?.title}
      </div>
    </nav>
  );
}

// =============================================================================
// MULTI-STEP FORM
// =============================================================================

/**
 * Multi-step form container
 * 
 * @example
 * ```tsx
 * const steps: FormChunk[] = [
 *   {
 *     id: 'contact',
 *     title: 'Contact',
 *     description: 'How can we reach you?',
 *     fields: ['email', 'phone'],
 *     schema: contactSchema
 *   },
 *   {
 *     id: 'address',
 *     title: 'Address',
 *     fields: ['street', 'city', 'state', 'zip'],
 *     schema: addressSchema
 *   }
 * ];
 * 
 * <MultiStepForm steps={steps} schema={fullSchema} onSubmit={handleSubmit}>
 *   {({ currentStep, step, next, back, isFirst, isLast }) => (
 *     <>
 *       {currentStep === 0 && <ContactFields />}
 *       {currentStep === 1 && <AddressFields />}
 *       
 *       <div className="buttons">
 *         {!isFirst && <button onClick={back}>Back</button>}
 *         {isLast ? (
 *           <button type="submit">Submit</button>
 *         ) : (
 *           <button onClick={next}>Next</button>
 *         )}
 *       </div>
 *     </>
 *   )}
 * </MultiStepForm>
 * ```
 */
export function MultiStepForm<T extends FieldValues>({
  steps,
  schema,
  onSubmit,
  defaultValues,
  children,
  showIndicator = true,
  submitLabel = 'Submit',
  nextLabel = 'Next',
  backLabel = 'Back'
}: MultiStepFormProps<T>) {
  const [currentStep, setCurrentStep] = useState(0);
  
  // Filter out skipped steps
  const activeSteps = steps.filter((step, index) => {
    if (!step.skipIf) return true;
    // Can't skip current step check until we have form values
    return true;
  });
  
  const form = useForm<T>({
    resolver: zodResolver(schema),
    mode: 'onBlur',
    reValidateMode: 'onChange',
    defaultValues: defaultValues as any
  });
  
  const totalSteps = activeSteps.length;
  const step = activeSteps[currentStep];
  const isFirst = currentStep === 0;
  const isLast = currentStep === totalSteps - 1;
  
  // Focus step heading on change
  const focusStepHeading = useCallback(() => {
    requestAnimationFrame(() => {
      const heading = document.getElementById('step-heading');
      if (heading) {
        heading.setAttribute('tabindex', '-1');
        heading.focus();
      }
    });
  }, []);
  
  // Validate current step and go to next
  const next = useCallback(async () => {
    if (!step) return false;
    
    // Validate only fields in current step
    const isValid = await form.trigger(step.fields as any);
    
    if (isValid && currentStep < totalSteps - 1) {
      setCurrentStep(prev => prev + 1);
      focusStepHeading();
      return true;
    }
    
    return isValid;
  }, [currentStep, step, totalSteps, form, focusStepHeading]);
  
  // Go to previous step
  const back = useCallback(() => {
    if (currentStep > 0) {
      setCurrentStep(prev => prev - 1);
      focusStepHeading();
    }
  }, [currentStep, focusStepHeading]);
  
  // Go to specific step (only completed steps)
  const goTo = useCallback((stepIndex: number) => {
    if (stepIndex >= 0 && stepIndex < currentStep) {
      setCurrentStep(stepIndex);
      focusStepHeading();
    }
  }, [currentStep, focusStepHeading]);
  
  // Handle form submission
  const handleSubmit = form.handleSubmit(async (data) => {
    await onSubmit(data);
  });
  
  const contextValue: MultiStepContextValue = {
    currentStep,
    totalSteps,
    goTo,
    next,
    back
  };
  
  const renderProps: MultiStepRenderProps<T> = {
    currentStep,
    totalSteps,
    step,
    next,
    back,
    goTo,
    isFirst,
    isLast,
    form,
    submit: handleSubmit
  };
  
  return (
    <MultiStepContext.Provider value={contextValue}>
      <FormProvider {...form}>
        <form onSubmit={handleSubmit} noValidate className="multi-step-form">
          {showIndicator && (
            <StepIndicator
              steps={activeSteps}
              currentStep={currentStep}
              onStepClick={goTo}
              allowNavigation={true}
            />
          )}
          
          {step && (
            <div className="multi-step-form__step">
              <h2 id="step-heading" className="multi-step-form__title">
                {step.title}
              </h2>
              
              {step.description && (
                <p className="multi-step-form__description">
                  {step.description}
                </p>
              )}
              
              <div className="multi-step-form__content">
                {typeof children === 'function' ? children(renderProps) : children}
              </div>
            </div>
          )}
          
          {/* Default navigation if not provided by children */}
          {typeof children !== 'function' && (
            <div className="multi-step-form__navigation">
              {!isFirst && (
                <button type="button" onClick={back} className="btn btn--secondary">
                  {backLabel}
                </button>
              )}
              
              {isLast ? (
                <button
                  type="submit"
                  disabled={form.formState.isSubmitting}
                  className="btn btn--primary"
                >
                  {form.formState.isSubmitting ? 'Submitting...' : submitLabel}
                </button>
              ) : (
                <button type="button" onClick={next} className="btn btn--primary">
                  {nextLabel}
                </button>
              )}
            </div>
          )}
        </form>
      </FormProvider>
    </MultiStepContext.Provider>
  );
}

// =============================================================================
// CONDITIONAL STEP
// =============================================================================

interface ConditionalStepProps {
  /** Condition function - receives form values */
  when: (values: FieldValues) => boolean;
  
  /** Content to show when condition is true */
  children: ReactNode;
}

/**
 * Conditionally render step content based on form values
 * 
 * @example
 * ```tsx
 * <ConditionalStep when={(values) => values.hasCompany}>
 *   <FormField name="companyName" label="Company Name" />
 * </ConditionalStep>
 * ```
 */
export function ConditionalStep({ when, children }: ConditionalStepProps) {
  const form = useForm();
  const values = form.watch();
  
  if (!when(values)) return null;
  return <>{children}</>;
}

// =============================================================================
// STEP CONTENT
// =============================================================================

interface StepContentProps {
  /** Step ID to match */
  step: string;
  
  /** Content for this step */
  children: ReactNode;
}

/**
 * Render content only for a specific step
 * 
 * @example
 * ```tsx
 * <MultiStepForm steps={steps} ...>
 *   <StepContent step="contact">
 *     <FormField name="email" label="Email" />
 *   </StepContent>
 *   
 *   <StepContent step="address">
 *     <FormField name="street" label="Street" />
 *   </StepContent>
 * </MultiStepForm>
 * ```
 */
export function StepContent({ step: stepId, children }: StepContentProps) {
  const { currentStep } = useMultiStep();
  
  // This would need access to steps array to match by ID
  // For now, assume steps are passed in order
  return <>{children}</>;
}

// =============================================================================
// CSS
// =============================================================================

export const multiStepFormCSS = `
/* Step Indicator */
.step-indicator {
  margin-bottom: 2rem;
}

.step-indicator__list {
  display: flex;
  justify-content: space-between;
  list-style: none;
  padding: 0;
  margin: 0;
}

.step-indicator__item {
  flex: 1;
  display: flex;
  align-items: center;
  position: relative;
}

.step-indicator__content,
.step-indicator__button {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 0.5rem;
  background: none;
  border: none;
  cursor: default;
  padding: 0;
}

.step-indicator__button {
  cursor: pointer;
}

.step-indicator__button:hover .step-indicator__number {
  background-color: #2563eb;
  color: white;
}

.step-indicator__number {
  width: 2rem;
  height: 2rem;
  border-radius: 50%;
  background-color: #e5e7eb;
  color: #6b7280;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: 500;
  transition: background-color 0.2s, color 0.2s;
}

.step-indicator__item.current .step-indicator__number {
  background-color: #2563eb;
  color: white;
}

.step-indicator__item.complete .step-indicator__number {
  background-color: #059669;
  color: white;
}

.step-indicator__title {
  font-size: 0.875rem;
  color: #6b7280;
}

.step-indicator__item.current .step-indicator__title {
  color: #111827;
  font-weight: 500;
}

.step-indicator__connector {
  flex: 1;
  height: 2px;
  background-color: #e5e7eb;
  margin: 0 0.5rem;
}

.step-indicator__item.complete .step-indicator__connector {
  background-color: #059669;
}

/* Multi-Step Form */
.multi-step-form__step {
  margin-bottom: 2rem;
}

.multi-step-form__title {
  font-size: 1.5rem;
  font-weight: 600;
  margin-bottom: 0.5rem;
  outline: none;
}

.multi-step-form__description {
  color: #6b7280;
  margin-bottom: 1.5rem;
}

.multi-step-form__navigation {
  display: flex;
  gap: 1rem;
  justify-content: space-between;
  padding-top: 1rem;
  border-top: 1px solid #e5e7eb;
}

/* Buttons */
.btn {
  padding: 0.75rem 1.5rem;
  border-radius: 0.375rem;
  font-weight: 500;
  cursor: pointer;
  transition: background-color 0.2s;
}

.btn--primary {
  background-color: #2563eb;
  color: white;
  border: none;
}

.btn--primary:hover {
  background-color: #1d4ed8;
}

.btn--primary:disabled {
  background-color: #93c5fd;
  cursor: not-allowed;
}

.btn--secondary {
  background-color: white;
  color: #374151;
  border: 1px solid #d1d5db;
}

.btn--secondary:hover {
  background-color: #f9fafb;
}
`;