Render Props - Compartilhe comportamento entre componentes passando uma função que retorna JSX

Q: Você deve exportar o tipo do argumento da render prop para os consumidores?

Sim. Exportar o tipo (por exemplo, DisclosureRenderProps) permite que os consumidores digitem suas funções de renderização externamente. Isso melhora o autocompletar e captura erros de tipo quando a função de renderização é definida em um arquivo separado.

Receita

// Um componente headless que gerencia a posição do mouse
function MouseTracker({ render }: {
  render: (position: { x: number; y: number }) => React.ReactNode;
}) {
  const [position, setPosition] = useState({ x: 0, y: 0 });
 
  const handleMouseMove = (e: React.MouseEvent) => {
    setPosition({ x: e.clientX, y: e.clientY });
  };
 
  return <div onMouseMove={handleMouseMove}>{render(position)}</div>;
}
 
// Uso
<MouseTracker
  render={({ x, y }) => <p>O mouse está em ({x}, {y})</p>}
/>

Quando usar isso: Quando um componente encapsula comportamento ou lógica de estado reutilizáveis e o consumidor precisa controlar o que é renderizado. Também útil para componentes de UI headless.

Exemplo Funcional

import { useState, useRef, useEffect, type ReactNode } from "react";
 
// Componente de divulgação headless usando render prop
interface DisclosureRenderProps {
  isOpen: boolean;
  toggle: () => void;
  open: () => void;
  close: () => void;
  triggerProps: {
    onClick: () => void;
    "aria-expanded": boolean;
    "aria-controls": string;
  };
  contentProps: {
    id: string;
    role: "region";
    hidden: boolean;
  };
}
 
function Disclosure({
  id,
  defaultOpen = false,
  children,
}: {
  id: string;
  defaultOpen?: boolean;
  children: (props: DisclosureRenderProps) => ReactNode;
}) {
  const [isOpen, setIsOpen] = useState(defaultOpen);
  const contentId = `${id}-content`;
 
  const api: DisclosureRenderProps = {
    isOpen,
    toggle: () => setIsOpen((prev) => !prev),
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    triggerProps: {
      onClick: () => setIsOpen((prev) => !prev),
      "aria-expanded": isOpen,
      "aria-controls": contentId,
    },
    contentProps: {
      id: contentId,
      role: "region",
      hidden: !isOpen,
    },
  };
 
  return <>{children(api)}</>;
}
 
// Uso - controle total sobre a renderização
function FAQ({ items }: { items: { q: string; a: string }[] }) {
  return (
    <div className="space-y-2">
      {items.map((item, i) => (
        <Disclosure key={i} id={`faq-${i}`}>
          {({ triggerProps, contentProps, isOpen }) => (
            <div className="border rounded-lg">
              <button
                {...triggerProps}
                className="w-full text-left p-4 font-medium flex justify-between"
              >
                {item.q}
                <span>{isOpen ? "−" : "+"}</span>
              </button>
              <div {...contentProps} className="px-4 pb-4 text-gray-600">
                {item.a}
              </div>
            </div>
          )}
        </Disclosure>
      ))}
    </div>
  );
}

O que isso demonstra:

Padrão function-as-children (a variante de render prop mais comum)
Componente headless - gerencia estado e ARIA, mas não renderiza nada por si só
O consumidor obtém controle total sobre a estrutura e o estilo do DOM
Props de acessibilidade são fornecidas pelo componente headless

Mergulho Profundo

Como Funciona

Uma render prop é qualquer prop cujo valor é uma função que retorna ReactNode.
O componente chama essa função durante a renderização, passando estado interno ou valores computados como argumentos.
A variante children (children: (props) => ReactNode) é a forma mais comum, às vezes chamada de "function-as-children".
O padrão separa comportamento (gerenciamento de estado, tratamento de eventos, acessibilidade) da apresentação (DOM, estilos).
Bibliotecas de UI headless (Headless UI, Radix primitives, Downshift) são construídas sobre esse conceito.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`render` ou `children`	`(state: T) => ReactNode`	Função que o consumidor fornece para controlar a renderização
Estado interno	Varia	Passado como argumento para a função de renderização
Manipuladores de eventos	`() => void` etc.	Fornecidos ao consumidor para vinculação aos seus próprios elementos
Props ARIA	Objetos espalhados	Atributos de acessibilidade pré-construídos para elementos do consumidor

Variações

Render prop nomeada - útil quando você precisa de vários slots de renderização:

function DataTable<T>({
  data,
  renderHeader,
  renderRow,
  renderEmpty,
}: {
  data: T[];
  renderHeader: () => ReactNode;
  renderRow: (item: T, index: number) => ReactNode;
  renderEmpty: () => ReactNode;
}) {
  if (data.length === 0) return <>{renderEmpty()}</>;
  return (
    <table>
      <thead>{renderHeader()}</thead>
      <tbody>{data.map((item, i) => renderRow(item, i))}</tbody>
    </table>
  );
}

Padrão de coleção de props - agrupa props relacionadas em objetos que podem ser espalhados:

// Em vez de props individuais:
// onClick={toggle} aria-expanded={isOpen} aria-controls={id}
 
// Fornece uma coleção:
// {...triggerProps}

Notas de TypeScript

Sempre digite o argumento da função de renderização explicitamente para que os consumidores obtenham autocompletar.
Use genéricos para render props que funcionam com tipos de dados variáveis: children: (item: T) => ReactNode.
Exporte o tipo do argumento da render prop para que os consumidores possam digitar suas funções de renderização externamente, se necessário.

Armadilhas

Nova função a cada renderização - Render props inline criam uma nova função a cada renderização, o que pode interferir com React.memo. Correção: Extraia a função de renderização para uma referência estável com useCallback se o componente pai for memoizado.
Inferno de wrappers - Aninhar múltiplos componentes de render prop cria indentação profunda. Correção: Extraia hooks personalizados para o comportamento em vez disso. A maioria dos padrões de render prop pode ser convertida em hooks.
Retornando fragmentos sem chaves - Quando render props retornam listas, cada item precisa de uma chave. Correção: Certifique-se de que o consumidor retorne elementos com chaves ao renderizar listas.
Quebrando regras de hooks dentro de render props - Você não pode chamar hooks dentro da função de renderização passada para uma render prop. Correção: Se hooks forem necessários, extraia um componente separado e passe os dados como props.

Alternativas

Abordagem	Trade-off
Render props	Controle total de renderização; pode levar a aninhamento
Hooks personalizados	API mais limpa; não pode encapsular a estrutura JSX
Composição (slots)	Mais simples; o conteúdo do slot não pode acessar o estado interno
Componentes de ordem superior	Adiciona comportamento transparentemente; mais difícil de tipar corretamente
Componentes compostos	Múltiplos elementos relacionados compartilham estado implicitamente

FAQs

Qual é a diferença entre uma render prop e function-as-children?

Uma render prop é qualquer prop cujo valor é uma função que retorna ReactNode.
Function-as-children é uma variante específica onde children é a função de renderização: children: (props) => ReactNode.
Function-as-children é a forma mais comum e evita o nome extra da prop.

O que é um componente headless?

Um componente headless gerencia estado, tratamento de eventos e acessibilidade, mas não renderiza nenhum DOM próprio.
O consumidor controla toda a renderização através de uma render prop.
Bibliotecas como Headless UI, Radix e Downshift são construídas sobre esse conceito.

Como o padrão de coleção de props simplifica as render props?

// Em vez de passar props individuais:
// onClick={toggle} aria-expanded={isOpen} aria-controls={id}
 
// Fornece um objeto que pode ser espalhado:
// {...triggerProps}

Agrupa props relacionadas (manipuladores de eventos, atributos ARIA) em um único objeto.
Os consumidores espalham o objeto em seu elemento, reduzindo o código repetitivo e evitando atributos perdidos.

Quando você deve usar múltiplas render props nomeadas em vez de uma única render prop children?

<DataTable
  data={rows}
  renderHeader={() => <tr><th>Nome</th></tr>}
  renderRow={(item) => <tr><td>{item.name}</td></tr>}
  renderEmpty={() => <p>Nenhum dado</p>}
/>

Use múltiplas render props nomeadas quando o componente tiver slots de renderização distintos (cabeçalho, linha, estado vazio).
Uma única render prop children funciona quando há apenas uma área de renderização.

Armadilha: Por que render props inline podem quebrar `React.memo`?

Funções de renderização inline criam uma nova referência de função a cada renderização.
Se o componente pai for memoizado, a nova referência fará com que ele re-renderize independentemente.
Correção: extraia a função de renderização e estabilize-a com useCallback se o componente pai for memoizado.

Armadilha: Você pode chamar hooks dentro de uma função de render prop?

Não. Hooks não podem ser chamados dentro da função de renderização passada para uma render prop.
A função é executada durante a renderização do pai, não como seu próprio componente.
Correção: extraia um componente separado que recebe os dados como props e chama hooks dentro desse componente.

Como você digita uma render prop genérica em TypeScript?

interface ListProps<T> {
  items: T[];
  children: (item: T, index: number) => ReactNode;
}
 
function List<T>({ items, children }: ListProps<T>) {
  return <ul>{items.map((item, i) => <li key={i}>{children(item, i)}</li>)}</ul>;
}

Use um parâmetro de tipo genérico tanto no componente quanto na função de renderização.
O TypeScript infere T do array items e o impõe no argumento da função de renderização.

Você deve exportar o tipo do argumento da render prop para os consumidores?

Sim. Exportar o tipo (por exemplo, DisclosureRenderProps) permite que os consumidores digitem suas funções de renderização externamente.
Isso melhora o autocompletar e captura erros de tipo quando a função de renderização é definida em um arquivo separado.

Por que as render props são menos comuns no React moderno e o que as substituiu?

Hooks personalizados podem encapsular o mesmo comportamento reutilizável sem aninhamento.
Hooks fornecem uma API mais limpa e evitam a indentação profunda ("inferno de wrappers") de render props aninhadas.
Render props ainda são úteis quando você precisa encapsular a estrutura JSX, não apenas a lógica.

Como as render props lidam com acessibilidade em comparação com a composição?

Render props podem fornecer objetos de atributos ARIA pré-construídos (como triggerProps e contentProps) para o consumidor espalhar.
O componente headless possui a lógica de acessibilidade, enquanto o consumidor possui a estrutura do DOM.
É assim que bibliotecas como Downshift e Headless UI fornecem widgets acessíveis sem ditar a marcação.

Como evitar o inferno de wrappers com múltiplos componentes de render prop?

Extraia o comportamento de cada componente de render prop para um hook personalizado.
Use os hooks juntos em um único componente em vez de aninhar wrappers de render prop.
A maioria dos padrões de render prop tem um equivalente direto em hook.

Relacionados

Composição - Alternativa mais simples quando os slots não precisam de estado interno
Componentes de Ordem Superior - Padrão alternativo para reutilização de comportamento
Componentes Compostos - API multi-parte que compartilha estado via contexto

Receita

// Um componente headless que gerencia a posição do mouse
function MouseTracker({ render }: {
  render: (position: { x: number; y: number }) => React.ReactNode;
}) {
  const [position, setPosition] = useState({ x: 0, y: 0 });
 
  const handleMouseMove = (e: React.MouseEvent) => {
    setPosition({ x: e.clientX, y: e.clientY });
  };
 
  return <div onMouseMove={handleMouseMove}>{render(position)}</div>;
}
 
// Uso
<MouseTracker
  render={({ x, y }) => <p>O mouse está em ({x}, {y})</p>}
/>

Exemplo Funcional

import { useState, useRef, useEffect, type ReactNode } from "react";
 
// Componente de divulgação headless usando render prop
interface DisclosureRenderProps {
  isOpen: boolean;
  toggle: () => void;
  open: () => void;
  close: () => void;
  triggerProps: {
    onClick: () => void;
    "aria-expanded": boolean;
    "aria-controls": string;
  };
  contentProps: {
    id: string;
    role: "region";
    hidden: boolean;
  };
}
 
function Disclosure({
  id,
  defaultOpen = false,
  children,
}: {
  id: string;
  defaultOpen?: boolean;
  children: (props: DisclosureRenderProps) => ReactNode;
}) {
  const [isOpen, setIsOpen] = useState(defaultOpen);
  const contentId = `${id}-content`;
 
  const api: DisclosureRenderProps = {
    isOpen,
    toggle: () => setIsOpen((prev) => !prev),
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    triggerProps: {
      onClick: () => setIsOpen((prev) => !prev),
      "aria-expanded": isOpen,
      "aria-controls": contentId,
    },
    contentProps: {
      id: contentId,
      role: "region",
      hidden: !isOpen,
    },
  };
 
  return <>{children(api)}</>;
}
 
// Uso - controle total sobre a renderização
function FAQ({ items }: { items: { q: string; a: string }[] }) {
  return (
    <div className="space-y-2">
      {items.map((item, i) => (
        <Disclosure key={i} id={`faq-${i}`}>
          {({ triggerProps, contentProps, isOpen }) => (
            <div className="border rounded-lg">
              <button
                {...triggerProps}
                className="w-full text-left p-4 font-medium flex justify-between"
              >
                {item.q}
                <span>{isOpen ? "−" : "+"}</span>
              </button>
              <div {...contentProps} className="px-4 pb-4 text-gray-600">
                {item.a}
              </div>
            </div>
          )}
        </Disclosure>
      ))}
    </div>
  );
}

O que isso demonstra:

Padrão function-as-children (a variante de render prop mais comum)
Componente headless - gerencia estado e ARIA, mas não renderiza nada por si só
O consumidor obtém controle total sobre a estrutura e o estilo do DOM
Props de acessibilidade são fornecidas pelo componente headless

Mergulho Profundo

Como Funciona

Uma render prop é qualquer prop cujo valor é uma função que retorna ReactNode.
O componente chama essa função durante a renderização, passando estado interno ou valores computados como argumentos.
A variante children (children: (props) => ReactNode) é a forma mais comum, às vezes chamada de "function-as-children".
O padrão separa comportamento (gerenciamento de estado, tratamento de eventos, acessibilidade) da apresentação (DOM, estilos).
Bibliotecas de UI headless (Headless UI, Radix primitives, Downshift) são construídas sobre esse conceito.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Propósito
`render` ou `children`	`(state: T) => ReactNode`	Função que o consumidor fornece para controlar a renderização
Estado interno	Varia	Passado como argumento para a função de renderização
Manipuladores de eventos	`() => void` etc.	Fornecidos ao consumidor para vinculação aos seus próprios elementos
Props ARIA	Objetos espalhados	Atributos de acessibilidade pré-construídos para elementos do consumidor

Variações

Render prop nomeada - útil quando você precisa de vários slots de renderização:

function DataTable<T>({
  data,
  renderHeader,
  renderRow,
  renderEmpty,
}: {
  data: T[];
  renderHeader: () => ReactNode;
  renderRow: (item: T, index: number) => ReactNode;
  renderEmpty: () => ReactNode;
}) {
  if (data.length === 0) return <>{renderEmpty()}</>;
  return (
    <table>
      <thead>{renderHeader()}</thead>
      <tbody>{data.map((item, i) => renderRow(item, i))}</tbody>
    </table>
  );
}

Padrão de coleção de props - agrupa props relacionadas em objetos que podem ser espalhados:

// Em vez de props individuais:
// onClick={toggle} aria-expanded={isOpen} aria-controls={id}
 
// Fornece uma coleção:
// {...triggerProps}

Notas de TypeScript

Sempre digite o argumento da função de renderização explicitamente para que os consumidores obtenham autocompletar.
Use genéricos para render props que funcionam com tipos de dados variáveis: children: (item: T) => ReactNode.
Exporte o tipo do argumento da render prop para que os consumidores possam digitar suas funções de renderização externamente, se necessário.

Armadilhas

Nova função a cada renderização - Render props inline criam uma nova função a cada renderização, o que pode interferir com React.memo. Correção: Extraia a função de renderização para uma referência estável com useCallback se o componente pai for memoizado.
Inferno de wrappers - Aninhar múltiplos componentes de render prop cria indentação profunda. Correção: Extraia hooks personalizados para o comportamento em vez disso. A maioria dos padrões de render prop pode ser convertida em hooks.
Retornando fragmentos sem chaves - Quando render props retornam listas, cada item precisa de uma chave. Correção: Certifique-se de que o consumidor retorne elementos com chaves ao renderizar listas.
Quebrando regras de hooks dentro de render props - Você não pode chamar hooks dentro da função de renderização passada para uma render prop. Correção: Se hooks forem necessários, extraia um componente separado e passe os dados como props.

Alternativas

Abordagem	Trade-off
Render props	Controle total de renderização; pode levar a aninhamento
Hooks personalizados	API mais limpa; não pode encapsular a estrutura JSX
Composição (slots)	Mais simples; o conteúdo do slot não pode acessar o estado interno
Componentes de ordem superior	Adiciona comportamento transparentemente; mais difícil de tipar corretamente
Componentes compostos	Múltiplos elementos relacionados compartilham estado implicitamente

FAQs

Qual é a diferença entre uma render prop e function-as-children?

Uma render prop é qualquer prop cujo valor é uma função que retorna ReactNode.
Function-as-children é uma variante específica onde children é a função de renderização: children: (props) => ReactNode.
Function-as-children é a forma mais comum e evita o nome extra da prop.

O que é um componente headless?

Um componente headless gerencia estado, tratamento de eventos e acessibilidade, mas não renderiza nenhum DOM próprio.
O consumidor controla toda a renderização através de uma render prop.
Bibliotecas como Headless UI, Radix e Downshift são construídas sobre esse conceito.

Como o padrão de coleção de props simplifica as render props?

// Em vez de passar props individuais:
// onClick={toggle} aria-expanded={isOpen} aria-controls={id}
 
// Fornece um objeto que pode ser espalhado:
// {...triggerProps}

Agrupa props relacionadas (manipuladores de eventos, atributos ARIA) em um único objeto.
Os consumidores espalham o objeto em seu elemento, reduzindo o código repetitivo e evitando atributos perdidos.

Quando você deve usar múltiplas render props nomeadas em vez de uma única render prop children?

<DataTable
  data={rows}
  renderHeader={() => <tr><th>Nome</th></tr>}
  renderRow={(item) => <tr><td>{item.name}</td></tr>}
  renderEmpty={() => <p>Nenhum dado</p>}
/>

Use múltiplas render props nomeadas quando o componente tiver slots de renderização distintos (cabeçalho, linha, estado vazio).
Uma única render prop children funciona quando há apenas uma área de renderização.

Armadilha: Por que render props inline podem quebrar `React.memo`?

Funções de renderização inline criam uma nova referência de função a cada renderização.
Se o componente pai for memoizado, a nova referência fará com que ele re-renderize independentemente.
Correção: extraia a função de renderização e estabilize-a com useCallback se o componente pai for memoizado.

Armadilha: Você pode chamar hooks dentro de uma função de render prop?

Não. Hooks não podem ser chamados dentro da função de renderização passada para uma render prop.
A função é executada durante a renderização do pai, não como seu próprio componente.
Correção: extraia um componente separado que recebe os dados como props e chama hooks dentro desse componente.

Como você digita uma render prop genérica em TypeScript?

interface ListProps<T> {
  items: T[];
  children: (item: T, index: number) => ReactNode;
}
 
function List<T>({ items, children }: ListProps<T>) {
  return <ul>{items.map((item, i) => <li key={i}>{children(item, i)}</li>)}</ul>;
}

Use um parâmetro de tipo genérico tanto no componente quanto na função de renderização.
O TypeScript infere T do array items e o impõe no argumento da função de renderização.

Você deve exportar o tipo do argumento da render prop para os consumidores?

Sim. Exportar o tipo (por exemplo, DisclosureRenderProps) permite que os consumidores digitem suas funções de renderização externamente.
Isso melhora o autocompletar e captura erros de tipo quando a função de renderização é definida em um arquivo separado.

Por que as render props são menos comuns no React moderno e o que as substituiu?

Hooks personalizados podem encapsular o mesmo comportamento reutilizável sem aninhamento.
Hooks fornecem uma API mais limpa e evitam a indentação profunda ("inferno de wrappers") de render props aninhadas.
Render props ainda são úteis quando você precisa encapsular a estrutura JSX, não apenas a lógica.

Como as render props lidam com acessibilidade em comparação com a composição?

Render props podem fornecer objetos de atributos ARIA pré-construídos (como triggerProps e contentProps) para o consumidor espalhar.
O componente headless possui a lógica de acessibilidade, enquanto o consumidor possui a estrutura do DOM.
É assim que bibliotecas como Downshift e Headless UI fornecem widgets acessíveis sem ditar a marcação.

Como evitar o inferno de wrappers com múltiplos componentes de render prop?

Extraia o comportamento de cada componente de render prop para um hook personalizado.
Use os hooks juntos em um único componente em vez de aninhar wrappers de render prop.
A maioria dos padrões de render prop tem um equivalente direto em hook.

Relacionados

Composição - Alternativa mais simples quando os slots não precisam de estado interno
Componentes de Ordem Superior - Padrão alternativo para reutilização de comportamento
Componentes Compostos - API multi-parte que compartilha estado via contexto

Render Props - Compartilhe comportamento entre componentes passando uma função que retorna JSX

Buscar na documentação

Render Props - Compartilhe comportamento entre componentes passando uma função que retorna JSX