Higher-Order Components - Aprimore componentes com comportamento compartilhado envolvendo-os em uma função

Q: Como você compõe múltiplos HOCs juntos?

HOCs podem ser aninhados ou combinados com uma utilidade compose. A composição é lida da direita para a esquerda: withAnalytics é aplicado primeiro, depois withTheme, depois withAuth.

Q: Por que displayName é importante para HOCs?

Sem displayName, o React DevTools mostra o componente wrapper como "Anonymous" ou com o nome interno do wrapper. Definir displayName para withAuth(Dashboard) torna a árvore de componentes legível. Sempre defina-o usando a propriedade displayName ou name do componente envolvido.

Q: Armadilha: Por que refs não passam por HOCs automaticamente?

ref não é uma prop regular no React; ele é tratado especialmente e removido antes de chegar ao componente envolvido. O wrapper HOC recebe a ref, não o componente interno. Correção: use React.forwardRef dentro do HOC para encaminhar refs ao componente envolvido.

Q: Como você tipa um HOC que injeta props em TypeScript?

Use Omit para remover props injetadas da API externa. Restrinja P extends InjectedProps para que o TypeScript saiba que o componente envolvido aceita essas props.

Q: Como usar Omit para excluir props injetadas da API externa de um HOC em TypeScript?

Omit remove os nomes das props injetadas do tipo que o consumidor vê. O consumidor não precisa passar theme ao usar withTheme(Component) porque o HOC o fornece. Sempre restrinja P extends object no mínimo para evitar parâmetros de tipo primitivo.

Receita

// HOC que adiciona controle de autenticação
function withAuth<P extends object>(
  WrappedComponent: React.ComponentType<P>
) {
  function AuthenticatedComponent(props: P) {
    const { user, isLoading } = useAuth();
 
    if (isLoading) return <LoadingSpinner />;
    if (!user) return <Navigate to="/login" />;
 
    return <WrappedComponent {...props} />;
  }
 
  AuthenticatedComponent.displayName =
    `withAuth(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
 
  return AuthenticatedComponent;
}
 
// Uso
const ProtectedDashboard = withAuth(Dashboard);

Quando usar isso: Quando você precisar aplicar a mesma preocupação transversal (autenticação, logging, temas, busca de dados) a muitos componentes sem modificá-los. Menos comum hoje em dia graças aos hooks, mas ainda útil para wrappers em nível de rota e integração com bibliotecas de terceiros.

Exemplo de Trabalho

import { useEffect, useRef, type ComponentType } from "react";
 
// HOC que rastreia a visibilidade do componente e relata análises
function withVisibilityTracking<P extends { id: string }>(
  WrappedComponent: ComponentType<P>,
  eventName: string
) {
  function TrackedComponent(props: P) {
    const ref = useRef<HTMLDivElement>(null);
    const reported = useRef(false);
 
    useEffect(() => {
      const element = ref.current;
      if (!element) return;
 
      const observer = new IntersectionObserver(
        ([entry]) => {
          if (entry.isIntersecting && !reported.current) {
            reported.current = true;
            analytics.track(eventName, { componentId: props.id });
          }
        },
        { threshold: 0.5 }
      );
 
      observer.observe(element);
      return () => observer.disconnect();
    }, [props.id]);
 
    return (
      <div ref={ref}>
        <WrappedComponent {...props} />
      </div>
    );
  }
 
  TrackedComponent.displayName =
    `withVisibilityTracking(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
 
  return TrackedComponent;
}
 
// Uso
interface ProductCardProps {
  id: string;
  name: string;
  price: number;
}
 
function ProductCard({ id, name, price }: ProductCardProps) {
  return (
    <div className="p-4 border rounded">
      <h3>{name}</h3>
      <p>${price}</p>
    </div>
  );
}
 
const TrackedProductCard = withVisibilityTracking(ProductCard, "product_viewed");
 
// Em uma página
function ProductGrid({ products }: { products: ProductCardProps[] }) {
  return (
    <div className="grid grid-cols-3 gap-4">
      {products.map((p) => (
        <TrackedProductCard key={p.id} {...p} />
      ))}
    </div>
  );
}

O que isso demonstra:

HOC que adiciona rastreamento IntersectionObserver sem modificar o componente original
Restrição de tipo genérico (P extends { id: string }) garante que o componente envolvido tenha as props necessárias
displayName definido para depuração do React DevTools
O ProductCard original permanece puro e testável por si só

Mergulho Profundo

Como Funciona

Um HOC é uma função que recebe um componente e retorna um novo componente com comportamento aprimorado.
O padrão segue o conceito matemático de composição de funções: enhance(Component) => EnhancedComponent.
O HOC não muta o componente original - ele o envolve em um novo.
O componente wrapper pode interceptar props, injetar novas props, renderizar condicionalmente ou adicionar efeitos de ciclo de vida.
Múltiplos HOCs podem ser compostos: withAuth(withTheme(withAnalytics(Component))).

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`WrappedComponent`	`ComponentType<P>`	O componente a ser aprimorado
Config (opcional)	Varia	Configuração para o comportamento do HOC
Valor de retorno	`ComponentType<P>` (ou modificado)	Um novo componente com comportamento adicionado

Variações

HOC de injeção de props - adiciona novas props ao componente envolvido:

interface WithThemeProps {
  theme: Theme;
}
 
function withTheme<P extends WithThemeProps>(
  WrappedComponent: ComponentType<P>
) {
  function ThemedComponent(props: Omit<P, keyof WithThemeProps>) {
    const theme = useTheme();
    return <WrappedComponent {...(props as P)} theme={theme} />;
  }
 
  ThemedComponent.displayName =
    `withTheme(${WrappedComponent.displayName ?? WrappedComponent.name})`;
 
  return ThemedComponent;
}

HOCs Compostos - combinam múltiplos aprimoramentos:

// Composição manual
const EnhancedComponent = withAuth(withTheme(withAnalytics(BaseComponent)));
 
// Com uma utilidade compose
import { compose } from "redux"; // ou escreva a sua
const enhance = compose(withAuth, withTheme, withAnalytics);
const EnhancedComponent = enhance(BaseComponent);

Notas do TypeScript

Use ComponentType<P> para aceitar componentes de função e de classe.
Use Omit<P, keyof InjectedProps> para remover props injetadas da API externa.
Sempre restrinja P extends object no mínimo para evitar tipos primitivos.
Defina displayName para cada HOC para tornar o React DevTools utilizável.
Considere usar React.forwardRef dentro de HOCs se o componente envolvido precisar de encaminhamento de ref.

Armadilhas

Encaminhamento de Ref - Refs não passam por HOCs automaticamente porque ref não é uma prop regular. Correção: Use React.forwardRef dentro do HOC wrapper.
Métodos estáticos perdidos - Propriedades estáticas no componente original não são copiadas para o wrapper. Correção: Use hoist-non-react-statics ou copie manualmente os estáticos necessários.
Colisões de nomes de props - Se o HOC injetar uma prop com o mesmo nome de uma prop existente, ela sobrescreve silenciosamente. Correção: Coloque em namespace as props injetadas ou use um prefixo único.
Recriando o HOC a cada renderização - Chamar um HOC dentro do corpo de um componente cria um novo tipo de componente a cada renderização, destruindo todo o estado. Correção: Sempre chame HOCs no escopo do módulo ou em um useMemo com extremo cuidado.
Dificuldade de depuração - HOCs profundamente aninhados criam árvores de componentes longas no DevTools. Correção: Defina displayName em cada HOC e considere se hooks seriam mais claros.

Alternativas

Abordagem	Trade-off
Higher-order components	Aprimoramento transparente; a tipagem é complexa, a depuração é mais difícil
Custom hooks	Mais simples, composable, melhores tipos; não pode envolver a renderização
Render props	Fluxo de dados explícito; mais verboso no local de chamada
Middleware (Next.js)	Melhor para preocupações em nível de rota como autenticação em aplicativos Next.js
Decorators (stage 3)	Açúcar sintático; ainda não amplamente suportado no ecossistema React

FAQs

O que exatamente é um higher-order component (HOC)?

Um HOC é uma função que recebe um componente e retorna um novo componente aprimorado.
Ele segue o padrão: enhance(Component) => EnhancedComponent.
O HOC envolve o componente original sem mutá-lo.

Por que os HOCs são menos comuns no React moderno?

Custom hooks podem alcançar a mesma reutilização de comportamento com uma API mais simples e composable.
Hooks são mais fáceis de tipar em TypeScript e produzem árvores de componentes mais limpas no DevTools.
HOCs ainda são úteis para wrappers em nível de rota e integração com bibliotecas de terceiros.

Como você compõe múltiplos HOCs juntos?

// Composição manual
const Enhanced = withAuth(withTheme(withAnalytics(Base)));
 
// Com uma utilidade compose
const enhance = compose(withAuth, withTheme, withAnalytics);
const Enhanced = enhance(Base);

HOCs podem ser aninhados ou combinados com uma utilidade compose.
A composição é lida da direita para a esquerda: withAnalytics é aplicado primeiro, depois withTheme, depois withAuth.

Por que `displayName` é importante para HOCs?

Sem displayName, o React DevTools mostra o componente wrapper como "Anonymous" ou com o nome interno do wrapper.
Definir displayName para withAuth(Dashboard) torna a árvore de componentes legível.
Sempre defina-o usando a propriedade displayName ou name do componente envolvido.

Armadilha: Por que chamar um HOC dentro do corpo de um componente destrói o estado?

Chamar um HOC dentro de render cria um novo tipo de componente a cada renderização.
O React trata cada novo tipo como um componente diferente e o desmonta/remonta, destruindo todo o estado.
Correção: sempre chame HOCs no escopo do módulo, fora de qualquer componente.

Armadilha: Por que refs não passam por HOCs automaticamente?

ref não é uma prop regular no React; ele é tratado especialmente e removido antes de chegar ao componente envolvido.
O wrapper HOC recebe a ref, não o componente interno.
Correção: use React.forwardRef dentro do HOC para encaminhar refs ao componente envolvido.

Como você tipa um HOC que injeta props em TypeScript?

interface WithThemeProps { theme: Theme; }
 
function withTheme<P extends WithThemeProps>(
  WrappedComponent: ComponentType<P>
) {
  function Themed(props: Omit<P, keyof WithThemeProps>) {
    const theme = useTheme();
    return <WrappedComponent {...(props as P)} theme={theme} />;
  }
  return Themed;
}

Use Omit<P, keyof InjectedProps> para remover props injetadas da API externa.
Restrinja P extends InjectedProps para que o TypeScript saiba que o componente envolvido aceita essas props.

Como usar `Omit` para excluir props injetadas da API externa de um HOC em TypeScript?

Omit<P, keyof InjectedProps> remove os nomes das props injetadas do tipo que o consumidor vê.
O consumidor não precisa passar theme ao usar withTheme(Component) porque o HOC o fornece.
Sempre restrinja P extends object no mínimo para evitar parâmetros de tipo primitivo.

O que acontece com os métodos estáticos quando você envolve um componente com um HOC?

Propriedades estáticas no componente original não são copiadas automaticamente para o wrapper HOC.
Correção: use o pacote hoist-non-react-statics ou copie manualmente os estáticos necessários.
Esta é uma fonte comum de bugs quando o componente envolvido tem métodos estáticos como getStaticProps.

Quais são as alternativas aos HOCs para aplicar preocupações transversais?

Custom hooks: mais simples, composable, melhor suporte a TypeScript, mas não podem envolver a renderização.
Render props: fluxo de dados explícito, mais verboso no local de chamada.
Middleware do Next.js: melhor para preocupações em nível de rota como autenticação.
Provedores de Contexto: bons para injeção de dependência sem envolvimento.

Como colisões de nomes de props podem causar bugs silenciosos em HOCs?

Se um HOC injetar uma prop com o mesmo nome de uma prop existente, o valor injetado sobrescreverá silenciosamente o valor do consumidor.
Isso é difícil de depurar porque não há erro ou aviso.
Correção: coloque em namespace as props injetadas (por exemplo, themeConfig em vez de config) ou use um prefixo único.

Relacionado

Render Props - Alternativa que dá aos consumidores controle de renderização
Composição - Preferível a HOCs quando o comportamento não é transversal
Padrões de Contexto - Frequentemente substitui HOCs para injeção de dependência

Receita

// HOC que adiciona controle de autenticação
function withAuth<P extends object>(
  WrappedComponent: React.ComponentType<P>
) {
  function AuthenticatedComponent(props: P) {
    const { user, isLoading } = useAuth();
 
    if (isLoading) return <LoadingSpinner />;
    if (!user) return <Navigate to="/login" />;
 
    return <WrappedComponent {...props} />;
  }
 
  AuthenticatedComponent.displayName =
    `withAuth(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
 
  return AuthenticatedComponent;
}
 
// Uso
const ProtectedDashboard = withAuth(Dashboard);

Exemplo de Trabalho

import { useEffect, useRef, type ComponentType } from "react";
 
// HOC que rastreia a visibilidade do componente e relata análises
function withVisibilityTracking<P extends { id: string }>(
  WrappedComponent: ComponentType<P>,
  eventName: string
) {
  function TrackedComponent(props: P) {
    const ref = useRef<HTMLDivElement>(null);
    const reported = useRef(false);
 
    useEffect(() => {
      const element = ref.current;
      if (!element) return;
 
      const observer = new IntersectionObserver(
        ([entry]) => {
          if (entry.isIntersecting && !reported.current) {
            reported.current = true;
            analytics.track(eventName, { componentId: props.id });
          }
        },
        { threshold: 0.5 }
      );
 
      observer.observe(element);
      return () => observer.disconnect();
    }, [props.id]);
 
    return (
      <div ref={ref}>
        <WrappedComponent {...props} />
      </div>
    );
  }
 
  TrackedComponent.displayName =
    `withVisibilityTracking(${WrappedComponent.displayName ?? WrappedComponent.name ?? "Component"})`;
 
  return TrackedComponent;
}
 
// Uso
interface ProductCardProps {
  id: string;
  name: string;
  price: number;
}
 
function ProductCard({ id, name, price }: ProductCardProps) {
  return (
    <div className="p-4 border rounded">
      <h3>{name}</h3>
      <p>${price}</p>
    </div>
  );
}
 
const TrackedProductCard = withVisibilityTracking(ProductCard, "product_viewed");
 
// Em uma página
function ProductGrid({ products }: { products: ProductCardProps[] }) {
  return (
    <div className="grid grid-cols-3 gap-4">
      {products.map((p) => (
        <TrackedProductCard key={p.id} {...p} />
      ))}
    </div>
  );
}

O que isso demonstra:

HOC que adiciona rastreamento IntersectionObserver sem modificar o componente original
Restrição de tipo genérico (P extends { id: string }) garante que o componente envolvido tenha as props necessárias
displayName definido para depuração do React DevTools
O ProductCard original permanece puro e testável por si só

Mergulho Profundo

Como Funciona

Um HOC é uma função que recebe um componente e retorna um novo componente com comportamento aprimorado.
O padrão segue o conceito matemático de composição de funções: enhance(Component) => EnhancedComponent.
O HOC não muta o componente original - ele o envolve em um novo.
O componente wrapper pode interceptar props, injetar novas props, renderizar condicionalmente ou adicionar efeitos de ciclo de vida.
Múltiplos HOCs podem ser compostos: withAuth(withTheme(withAnalytics(Component))).

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`WrappedComponent`	`ComponentType<P>`	O componente a ser aprimorado
Config (opcional)	Varia	Configuração para o comportamento do HOC
Valor de retorno	`ComponentType<P>` (ou modificado)	Um novo componente com comportamento adicionado

Variações

HOC de injeção de props - adiciona novas props ao componente envolvido:

interface WithThemeProps {
  theme: Theme;
}
 
function withTheme<P extends WithThemeProps>(
  WrappedComponent: ComponentType<P>
) {
  function ThemedComponent(props: Omit<P, keyof WithThemeProps>) {
    const theme = useTheme();
    return <WrappedComponent {...(props as P)} theme={theme} />;
  }
 
  ThemedComponent.displayName =
    `withTheme(${WrappedComponent.displayName ?? WrappedComponent.name})`;
 
  return ThemedComponent;
}

HOCs Compostos - combinam múltiplos aprimoramentos:

// Composição manual
const EnhancedComponent = withAuth(withTheme(withAnalytics(BaseComponent)));
 
// Com uma utilidade compose
import { compose } from "redux"; // ou escreva a sua
const enhance = compose(withAuth, withTheme, withAnalytics);
const EnhancedComponent = enhance(BaseComponent);

Notas do TypeScript

Use ComponentType<P> para aceitar componentes de função e de classe.
Use Omit<P, keyof InjectedProps> para remover props injetadas da API externa.
Sempre restrinja P extends object no mínimo para evitar tipos primitivos.
Defina displayName para cada HOC para tornar o React DevTools utilizável.
Considere usar React.forwardRef dentro de HOCs se o componente envolvido precisar de encaminhamento de ref.

Armadilhas

Encaminhamento de Ref - Refs não passam por HOCs automaticamente porque ref não é uma prop regular. Correção: Use React.forwardRef dentro do HOC wrapper.
Métodos estáticos perdidos - Propriedades estáticas no componente original não são copiadas para o wrapper. Correção: Use hoist-non-react-statics ou copie manualmente os estáticos necessários.
Colisões de nomes de props - Se o HOC injetar uma prop com o mesmo nome de uma prop existente, ela sobrescreve silenciosamente. Correção: Coloque em namespace as props injetadas ou use um prefixo único.
Recriando o HOC a cada renderização - Chamar um HOC dentro do corpo de um componente cria um novo tipo de componente a cada renderização, destruindo todo o estado. Correção: Sempre chame HOCs no escopo do módulo ou em um useMemo com extremo cuidado.
Dificuldade de depuração - HOCs profundamente aninhados criam árvores de componentes longas no DevTools. Correção: Defina displayName em cada HOC e considere se hooks seriam mais claros.

Alternativas

Abordagem	Trade-off
Higher-order components	Aprimoramento transparente; a tipagem é complexa, a depuração é mais difícil
Custom hooks	Mais simples, composable, melhores tipos; não pode envolver a renderização
Render props	Fluxo de dados explícito; mais verboso no local de chamada
Middleware (Next.js)	Melhor para preocupações em nível de rota como autenticação em aplicativos Next.js
Decorators (stage 3)	Açúcar sintático; ainda não amplamente suportado no ecossistema React

FAQs

O que exatamente é um higher-order component (HOC)?

Um HOC é uma função que recebe um componente e retorna um novo componente aprimorado.
Ele segue o padrão: enhance(Component) => EnhancedComponent.
O HOC envolve o componente original sem mutá-lo.

Por que os HOCs são menos comuns no React moderno?

Custom hooks podem alcançar a mesma reutilização de comportamento com uma API mais simples e composable.
Hooks são mais fáceis de tipar em TypeScript e produzem árvores de componentes mais limpas no DevTools.
HOCs ainda são úteis para wrappers em nível de rota e integração com bibliotecas de terceiros.

Como você compõe múltiplos HOCs juntos?

// Composição manual
const Enhanced = withAuth(withTheme(withAnalytics(Base)));
 
// Com uma utilidade compose
const enhance = compose(withAuth, withTheme, withAnalytics);
const Enhanced = enhance(Base);

HOCs podem ser aninhados ou combinados com uma utilidade compose.
A composição é lida da direita para a esquerda: withAnalytics é aplicado primeiro, depois withTheme, depois withAuth.

Por que `displayName` é importante para HOCs?

Sem displayName, o React DevTools mostra o componente wrapper como "Anonymous" ou com o nome interno do wrapper.
Definir displayName para withAuth(Dashboard) torna a árvore de componentes legível.
Sempre defina-o usando a propriedade displayName ou name do componente envolvido.

Armadilha: Por que chamar um HOC dentro do corpo de um componente destrói o estado?

Chamar um HOC dentro de render cria um novo tipo de componente a cada renderização.
O React trata cada novo tipo como um componente diferente e o desmonta/remonta, destruindo todo o estado.
Correção: sempre chame HOCs no escopo do módulo, fora de qualquer componente.

Armadilha: Por que refs não passam por HOCs automaticamente?

ref não é uma prop regular no React; ele é tratado especialmente e removido antes de chegar ao componente envolvido.
O wrapper HOC recebe a ref, não o componente interno.
Correção: use React.forwardRef dentro do HOC para encaminhar refs ao componente envolvido.

Como você tipa um HOC que injeta props em TypeScript?

interface WithThemeProps { theme: Theme; }
 
function withTheme<P extends WithThemeProps>(
  WrappedComponent: ComponentType<P>
) {
  function Themed(props: Omit<P, keyof WithThemeProps>) {
    const theme = useTheme();
    return <WrappedComponent {...(props as P)} theme={theme} />;
  }
  return Themed;
}

Use Omit<P, keyof InjectedProps> para remover props injetadas da API externa.
Restrinja P extends InjectedProps para que o TypeScript saiba que o componente envolvido aceita essas props.

Como usar `Omit` para excluir props injetadas da API externa de um HOC em TypeScript?

Omit<P, keyof InjectedProps> remove os nomes das props injetadas do tipo que o consumidor vê.
O consumidor não precisa passar theme ao usar withTheme(Component) porque o HOC o fornece.
Sempre restrinja P extends object no mínimo para evitar parâmetros de tipo primitivo.

O que acontece com os métodos estáticos quando você envolve um componente com um HOC?

Propriedades estáticas no componente original não são copiadas automaticamente para o wrapper HOC.
Correção: use o pacote hoist-non-react-statics ou copie manualmente os estáticos necessários.
Esta é uma fonte comum de bugs quando o componente envolvido tem métodos estáticos como getStaticProps.

Quais são as alternativas aos HOCs para aplicar preocupações transversais?

Custom hooks: mais simples, composable, melhor suporte a TypeScript, mas não podem envolver a renderização.
Render props: fluxo de dados explícito, mais verboso no local de chamada.
Middleware do Next.js: melhor para preocupações em nível de rota como autenticação.
Provedores de Contexto: bons para injeção de dependência sem envolvimento.

Como colisões de nomes de props podem causar bugs silenciosos em HOCs?

Se um HOC injetar uma prop com o mesmo nome de uma prop existente, o valor injetado sobrescreverá silenciosamente o valor do consumidor.
Isso é difícil de depurar porque não há erro ou aviso.
Correção: coloque em namespace as props injetadas (por exemplo, themeConfig em vez de config) ou use um prefixo único.

Relacionado

Render Props - Alternativa que dá aos consumidores controle de renderização
Composição - Preferível a HOCs quando o comportamento não é transversal
Padrões de Contexto - Frequentemente substitui HOCs para injeção de dependência

Higher-Order Components - Aprimore componentes com comportamento compartilhado envolvendo-os em uma função

Buscar na documentação

Higher-Order Components - Aprimore componentes com comportamento compartilhado envolvendo-os em uma função