Architecture Walkthrough

The Wrapping Contract and Why Props Must Flow Through

The fundamental contract of a HOC is that the returned component must behave as a transparent pass-through for all props that are not consumed by the HOC itself. Every HOC must spread {...props} onto the wrapped component. If you omit this, any prop the parent passes (className, style, event handlers, data attributes) is silently swallowed by the HOC, and the wrapped component receives only what the HOC explicitly passes. This is the most common HOC bug: a developer adds authentication checking but forgets to forward props, and the wrapped component stops receiving its data.

displayName and the React DevTools Debugging Problem

When React renders components, it uses the function or class name to display them in the component tree in DevTools. When you create a HOC, the returned function is anonymous or named generically. In a codebase with several HOC-wrapped components, the DevTools tree becomes a list of identically named wrappers with no indication of what is inside each one. The fix is to set displayName on the returned component immediately, following the convention of `withAuth(${WrappedComponent.displayName || WrappedComponent.name})`. The || WrappedComponent.name fallback matters because displayName is not set by default on user-defined components.

Ref Forwarding and the Static Methods Problem

When a parent attaches a ref to withAuth(Dashboard), the ref points to the HOC's returned function component, not to the inner Dashboard. Function components cannot hold refs by default, so the ref is null. The fix is to use React.forwardRef in the HOC and pass the ref through to the wrapped component. The static methods problem is less obvious: if Dashboard has a static method like Dashboard.fetchData, the HOC-wrapped version does not automatically inherit it. The library hoist-non-react-statics copies static methods from the wrapped component to the wrapper.

Never Define HOCs Inside Render Functions

A HOC creates a new component type. If the HOC call is inside a render function, React creates a new component type on every render. React uses component identity (reference equality of the constructor/function) to decide whether to remount. A new component type on every render means React unmounts and remounts the wrapped component on every parent render, destroying all state and causing full DOM replacement. HOCs must be defined at module scope, not inside components.

Key Code Explained

import React from 'react';
import { useAuth } from '@/common/hooks/useAuth';
import { Navigate } from 'react-router-dom';

// withAuth HOC: adds authentication check before rendering
function withAuth<P extends object>(WrappedComponent: React.ComponentType<P>) {
  // Name the inner function for DevTools readability
  function AuthGuard(props: P) {
    const { user, isLoading } = useAuth();

    if (isLoading) return <Spinner />;
    if (!user) return <Navigate to="/login" replace />;

    // {...props} is mandatory — forwards all parent props to the wrapped component
    return <WrappedComponent {...props} />;
  }

  // Set displayName for React DevTools
  AuthGuard.displayName = `withAuth(${
    WrappedComponent.displayName ?? WrappedComponent.name
  })`;

  return AuthGuard;
}

// Usage: wrapping at module level — never inside a component render
const ProtectedDashboard = withAuth(Dashboard);


// HOC that consumes one prop and forwards the rest
function withPageTracking<P extends { pageName: string }>(
  WrappedComponent: React.ComponentType<Omit<P, 'pageName'>>
) {
  function Tracked({ pageName, ...rest }: P) {
    useEffect(() => {
      analytics.track('page_view', { page: pageName });
    }, [pageName]);

    // Destructure pageName out before spreading — prevents it leaking to the DOM
    return <WrappedComponent {...(rest as Omit<P, 'pageName'>)} />;
  }

  Tracked.displayName = `withPageTracking(${
    WrappedComponent.displayName ?? WrappedComponent.name
  })`;

  return Tracked;
}


// HOC with ref forwarding: use React.forwardRef so parent refs reach the inner element
function withHighlight<P extends object>(WrappedComponent: React.ComponentType<P>) {
  const Highlighted = React.forwardRef<HTMLElement, P>((props, ref) => {
    return (
      <div style={{ boxShadow: '0 0 0 2px var(--accent)' }}>
        {/* Pass the ref through to the wrapped component */}
        <WrappedComponent {...props} ref={ref} />
      </div>
    );
  });

  Highlighted.displayName = `withHighlight(${
    WrappedComponent.displayName ?? WrappedComponent.name
  })`;

  return Highlighted;
}


// Composing multiple HOCs: read inside-out
// withAnalytics(withPermissions(withAuth(Dashboard)))
// Execution order: withAuth runs first (outermost call), withAnalytics runs last
const EnhancedDashboard = withAnalytics(withPermissions(withAuth(Dashboard)));

The pageName destructuring in withPageTracking is the correct pattern when the HOC consumes a prop that the wrapped component should not receive. Without it, pageName leaks into the wrapped component's props. If the wrapped component renders it onto a native DOM element, React logs a DOM attribute warning.

Tradeoffs

What Interviewers Actually Check

• Whether you spread {...props} and can describe the exact failure mode when you do not
• Whether you set displayName with the wrapped component name convention
• Whether you know HOCs must be defined outside render functions and can explain the remount bug
• Whether you know React.forwardRef is required for ref forwarding and can sketch the implementation
• Whether you can articulate when a HOC is still the right choice over a custom hook

Follow-Up Questions

1. Your withAuth HOC is defined inside another component's render function. What bug does this introduce, and how do you fix it?
2. A parent component passes a ref to withAuth(Dashboard) and receives null. Walk through exactly why this happens and what changes are needed in the HOC.
3. Dashboard has a static fetchData method used by your data prefetching system. After wrapping with withAuth, the prefetching breaks. Why, and what tool or technique fixes this?
4. You are composing four HOCs and the DevTools tree shows four layers of Enhanced. How do you make this readable without refactoring the HOC logic?
5. A product manager says every page needs an A/B test variant. The engineering team proposes a withABTest HOC. What risks do you flag about prop collision and component identity before approving this?

Common Candidate Mistakes

• Forgetting {...props} spread — the wrapped component receives no props from the parent and renders incorrectly
• Not setting displayName — identical "Enhanced" or anonymous wrappers in DevTools make debugging multi-HOC components painful
• Defining the HOC call inside a component's render return or body — creates a new component type per render, causing full remounts and state loss
• Not using React.forwardRef — refs from parents are null because they point to the HOC wrapper function, not the inner DOM node
• Not hoisting static methods from the wrapped component — silent runtime failures for data prefetching and route-level patterns

Interview Readiness Checklist

Before you leave this question, make sure you can answer:

• Can you implement a HOC that spreads {...props} and sets displayName?
• Can you explain what happens if {...props} is omitted?
• Can you explain why HOCs defined inside render functions cause remount bugs?
• Can you use React.forwardRef inside a HOC and explain why it is needed?
• Can you articulate when a HOC is the right choice over a custom hook?

Summary

A HOC is a function that takes a component and returns an enhanced version with added cross-cutting behavior such as authentication, analytics, or permissions, without modifying the wrapped component. Three disciplines are required for production-correct HOCs: always spread {...props} to avoid swallowing parent props, always set displayName using the wrapped component name for readable DevTools output, and always use React.forwardRef when refs must reach the inner component. HOCs must be defined at module scope, never inside render functions, because React uses component reference identity for reconciliation and creates a new component type on every render otherwise. HOCs are largely superseded by custom hooks for logic sharing, but they remain the correct tool when you need to intercept and conditionally prevent rendering based on auth state, permissions, or feature flags.