Componentes Compostos

Q: O que torna um componente composto?

Um componente pai fornece estado compartilhado através de context (ou cloneElement em padrões mais antigos). Os filhos são partes nomeadas compostas em JSX, não objetos de configuração opacos. O chamador controla a estrutura e a ordem - a biblioteca não codifica um layout fixo.

Q: Componentes compostos vs React Context - qual a diferença?

Componentes compostos são um padrão construído sobre context (ou estado com escopo). Context bruto exporta um provedor e um hook; o composto envolve isso em subcomponentes ergonômicos. Prefira compostos para APIs de design system; context bruto para tema ou autenticação em nível de aplicativo.

Q: Painéis de abas inativos devem permanecer montados?

Desmonte quando os painéis executam efeitos pesados, visualizações de mapas ou players de vídeo. Mantenha montado ao retornar para preservar a posição de rolagem ou a entrada do formulário. Exponha unmountOnBlur?: boolean na raiz se ambos os casos de uso forem importantes.

Q: Como tipar propriedades estáticas como Tabs.List?

Defina a função raiz, depois intercale com { List: typeof TabList; ... }. Faça um cast uma vez ao anexar partes, ou construa um literal de objeto e afirme o tipo do namespace. Re-exporte um único símbolo Tabs para que os consumidores importem um nome.

Q: Componentes compostos podem funcionar com layouts do Expo Router?

Sim - um layout pode renderizar em torno de um para rotas aninhadas. Abas baseadas em rotas ainda se beneficiam de gatilhos compostos que chamam router.push. Veja Render Props & Slot Patterns para composição de slots.

Q: Como compostos de campos de formulário se integram com bibliotecas de validação?

O FieldGroup raiz aceita error de fieldState.error?.message do React Hook Form. Mantenha a lógica de validação fora do composto - ele apenas exibe o chrome de erro. Passe onChangeText / value através de FieldGroup.Input sem alterações.

Q: Armadilha: Colisões de useId entre servidores?

useId é por árvore React - seguro para IDs de itens de acordeão em dispositivos móveis. Não persista a saída de useId no armazenamento; gere IDs de servidor separadamente para APIs.

Componentes compostos permitem que os chamadores montem UIs flexíveis - abas, cards, grupos de campos de formulário - a partir de partes nomeadas que compartilham estado implícito. O componente pai possui activeIndex ou isExpanded; filhos como Tabs.List e Tabs.Panel o leem através do context, em vez de passar props através de todos os slots.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { createContext, useContext, useState, type ReactNode } from "react";
import { Pressable, Text, View } from "react-native";
 
interface TabsContextValue {
  activeIndex: number;
  setActiveIndex: (index: number) => void;
}
 
const TabsContext = createContext<TabsContextValue | null>(null);
 
function useTabsContext() {
  const ctx = useContext(TabsContext);
  if (!ctx) throw new Error("Tabs.* deve ser usado dentro de <Tabs>");
  return ctx;
}
 
function Tabs({ defaultIndex = 0, children }: { defaultIndex?: number; children: ReactNode }) {
  const [activeIndex, setActiveIndex] = useState(defaultIndex);
  return (
    <TabsContext.Provider value={{ activeIndex, setActiveIndex }}>
      <View>{children}</View>
    </TabsContext.Provider>
  );
}
 
function TabList({ children }: { children: ReactNode }) {
  return <View style={{ flexDirection: "row", gap: 8 }}>{children}</View>;
}
 
function Tab({ index, children }: { index: number; children: ReactNode }) {
  const { activeIndex, setActiveIndex } = useTabsContext();
  const active = activeIndex === index;
  return (
    <Pressable onPress={() => setActiveIndex(index)}>
      <Text style={{ fontWeight: active ? "700" : "400" }}>{children}</Text>
    </Pressable>
  );
}
 
function TabPanel({ index, children }: { index: number; children: ReactNode }) {
  const { activeIndex } = useTabsContext();
  if (activeIndex !== index) return null;
  return <View>{children}</View>;
}
 
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;
 
// Consumidor - reordene, omita ou reestilize partes livremente
export function SettingsScreen() {
  return (
    <Tabs defaultIndex={0}>
      <Tabs.List>
        <Tabs.Tab index={0}>Conta</Tabs.Tab>
        <Tabs.Tab index={1}>Privacidade</Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel index={0}>
        <Text>Configurações da conta</Text>
      </Tabs.Panel>
      <Tabs.Panel index={1}>
        <Text>Configurações de privacidade</Text>
      </Tabs.Panel>
    </Tabs>
  );
}

Quando usar isso:

Várias partes filhas precisam do mesmo estado do componente pai (aba ativa, seção aberta, erro de campo).
Listas de props como tabLabels, tabContents, onTabChange conflitam com layouts flexíveis.
Primitivos de design system devem permanecer sem estilo enquanto as equipes de produto compõem a estrutura.
Você deseja uma API que se pareça com JSX - <Card.Header> em vez de renderHeader().
Layouts móveis precisam reordenar elementos visuais (abas na parte inferior em celulares, na lateral em tablets) sem alterações na API.

Exemplo de Trabalho

import {
  createContext,
  useCallback,
  useContext,
  useId,
  useMemo,
  useState,
  type ReactNode,
} from "react";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
interface AccordionContextValue {
  openId: string | null;
  toggle: (id: string) => void;
}
 
const AccordionContext = createContext<AccordionContextValue | null>(null);
 
function useAccordion() {
  const ctx = useContext(AccordionContext);
  if (!ctx) throw new Error("Accordion.* deve ser usado dentro de <Accordion>");
  return ctx;
}
 
interface AccordionProps {
  children: ReactNode;
  defaultOpenId?: string | null;
}
 
function Accordion({ children, defaultOpenId = null }: AccordionProps) {
  const [openId, setOpenId] = useState<string | null>(defaultOpenId);
 
  const toggle = useCallback((id: string) => {
    setOpenId((current) => (current === id ? null : id));
  }, []);
 
  const value = useMemo(() => ({ openId, toggle }), [openId, toggle]);
 
  return (
    <AccordionContext.Provider value={value}>
      <View style={styles.accordion}>{children}</View>
    </AccordionContext.Provider>
  );
}
 
interface ItemProps {
  title: string;
  children: ReactNode;
}
 
function AccordionItem({ title, children }: ItemProps) {
  const id = useId();
  const { openId, toggle } = useAccordion();
  const open = openId === id;
 
  return (
    <View style={styles.item}>
      <Pressable
        onPress={() => toggle(id)}
        style={styles.trigger}
        accessibilityRole="button"
        accessibilityState={{ expanded: open }}
      >
        <Text style={styles.triggerText}>{title}</Text>
        <Text style={styles.chevron}>{open ? "▾" : "▸"}</Text>
      </Pressable>
      {open ? <View style={styles.panel}>{children}</View> : null}
    </View>
  );
}
 
interface FieldGroupContextValue {
  error?: string;
}
 
const FieldGroupContext = createContext<FieldGroupContextValue>({});
 
interface FieldGroupProps {
  label: string;
  error?: string;
  children: ReactNode;
}
 
function FieldGroup({ label, error, children }: FieldGroupProps) {
  const value = useMemo(() => ({ error }), [error]);
  return (
    <FieldGroupContext.Provider value={value}>
      <View style={styles.fieldGroup}>
        <Text style={styles.label}>{label}</Text>
        {children}
        {error ? <Text style={styles.error}>{error}</Text> : null}
      </View>
    </FieldGroupContext.Provider>
  );
}
 
function FieldInput(props: React.ComponentProps<typeof TextInput>) {
  const { error } = useContext(FieldGroupContext);
  return (
    <TextInput
      {...props}
      style={[styles.input, error && styles.inputError, props.style]}
      placeholderTextColor="#94a3b8"
    />
  );
}
 
FieldGroup.Input = FieldInput;
 
export default function ProfileFormScreen() {
  const [name, setName] = useState("");
  const nameError = name.length > 0 && name.length < 2 ? "O nome é muito curto" : undefined;
 
  return (
    <View style={styles.screen}>
      <Text style={styles.heading}>Perfil</Text>
 
      <Accordion defaultOpenId={null}>
        <AccordionItem title="Informações pessoais">
          <FieldGroup label="Nome de exibição" error={nameError}>
            <FieldGroup.Input
              value={name}
              onChangeText={setName}
              placeholder="Jane Doe"
              autoCapitalize="words"
            />
          </FieldGroup>
        </AccordionItem>
 
        <AccordionItem title="Notificações">
          <Text style={styles.body}>
            Preferências de push e e-mail ficam aqui. O acordeão mantém a tela
            curta em celulares pequenos.
          </Text>
        </AccordionItem>
      </Accordion>
    </View>
  );
}
 
Accordion.Item = AccordionItem;
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 16, backgroundColor: "#f8fafc", gap: 16 },
  heading: { fontSize: 24, fontWeight: "700", color: "#0f172a" },
  accordion: { gap: 8 },
  item: { backgroundColor: "#fff", borderRadius: 12, overflow: "hidden" },
  trigger: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    padding: 16,
  },
  triggerText: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  chevron: { fontSize: 14, color: "#64748b" },
  panel: { paddingHorizontal: 16, paddingBottom: 16, gap: 12 },
  fieldGroup: { gap: 6 },
  label: { fontSize: 14, fontWeight: "600", color: "#334155" },
  input: {
    borderWidth: 1,
    borderColor: "#cbd5e1",
    borderRadius: 10,
    padding: 12,
    fontSize: 16,
    backgroundColor: "#fff",
    color: "#0f172a",
  },
  inputError: { borderColor: "#dc2626" },
  error: { fontSize: 13, color: "#dc2626" },
  body: { fontSize: 15, color: "#475569", lineHeight: 22 },
});

O que isso demonstra:

Accordion possui openId; AccordionItem gera um useId() estável e lê a lógica de alternância compartilhada.
FieldGroup + FieldGroup.Input compartilham o estilo de erro sem passar error para cada prop de input.
Propriedades estáticas (Accordion.Item, FieldGroup.Input) expõem uma API de namespace descobrível.
Os consumidores controlam a ordem e a aninhamento - a cópia de notificações pode ficar ao lado do campo de nome sem alterações na API.
Valores de context são memoizados para evitar re-renderizar cada item quando um estado não relacionado muda.

Mergulho Profundo

Como Funciona

O componente composto raiz detém o estado (activeIndex, openId, variant) e o fornece via React.createContext.
Subcomponentes chamam useContext (envolvido em um hook customizado) para ler e atualizar o estado compartilhado.
Os filhos são compostos em JSX - o componente pai não mapeia sobre arrays de configuração para renderizar slots.
Atribuição estática (Tabs.List = TabList) anexa partes à exportação raiz para ergonomia de importação única.
O React 19 ainda reconcilia os filhos normalmente; as partes compostas são componentes de função comuns.
Lançar um erro quando o context é null falha rapidamente em desenvolvimento se uma parte for usada fora de seu provedor.

Blocos de Construção da API Composta

Peça	Responsabilidade	Nota RN
Raiz (`<Tabs>`)	Estado, provedor, shell de layout opcional	Frequentemente uma `View` com `gap` - sem `ScrollView` a menos que necessário
Lista / chrome (`Tabs.List`)	Agrupa gatilhos	Use `flexDirection: "row"` ou coluna para abas inferiores
Gatilho (`Tabs.Tab`)	`Pressable` + `accessibilityRole`	Marque `accessibilityState={{ selected: active }}`
Painel (`Tabs.Panel`)	Renderização condicional ou `display: "none"`	Desmonte painéis ocultos para economizar memória em telas pesadas
Input folha (`FieldGroup.Input`)	Encaminha refs/props para o primitivo	Espalhe props de `TextInput`; não codifique tipos de teclado

Estabilidade do Valor do Context

// Instável - novo objeto a cada renderização re-renderiza todos os consumidores
<TabsContext.Provider value={{ activeIndex, setActiveIndex }}>
 
// Estável - memoize; estabilize setters com useCallback na raiz
const value = useMemo(
  () => ({ activeIndex, setActiveIndex }),
  [activeIndex, setActiveIndex]
);

Apenas descendentes que leem um campo alterado re-renderizam quando o context atualiza.
Divida context "quente" e "frio" se necessário: TabsStateContext + TabsActionsContext para árvores grandes.
Para atualizações de alta frequência (controladores animados), prefira um hook ou ref em vez de context.

Notas de TypeScript

import type { ReactNode } from "react";
 
// Tipagem de namespace com partes estáticas
type TabsComponent = ((props: TabsProps) => JSX.Element) & {
  List: typeof TabList;
  Tab: typeof Tab;
  Panel: typeof TabPanel;
};
 
const Tabs = RootTabs as TabsComponent;
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;
 
// Props discriminadas em itens - combinações inválidas falham em tempo de compilação
type FormFieldProps =
  | { kind: "text"; value: string; onChangeText: (t: string) => void }
  | { kind: "switch"; value: boolean; onValueChange: (v: boolean) => void };

Exporte hooks de context como useTabsContext - não exporte context bruto, a menos que seja para testes.
Tipifique partes estáticas com tipos de interseção para que Tabs.List tenha autocompletar no IDE.
Veja Typing Components & Props para uniões discriminadas em partes variantes.

Armadilhas

Guarda de provedor ausente - Usar Tabs.Tab fora de <Tabs> lê context null e se comporta silenciosamente de forma incorreta. Correção: Lance um erro em useTabsContext() com uma mensagem clara.
Valor de context instável - value={{ activeIndex, setActiveIndex }} inline re-renderiza cada consumidor a cada renderização do pai. Correção: Use useMemo para o valor; envolva setters em useCallback.
Abas baseadas em índice quebram na reordenação - index={2} codificado à mão muda quando o marketing insere uma aba. Correção: Use IDs de string ("account") como chaves internamente para as abas; mapeie para índice se necessário.
Montagem de todos os painéis de uma vez - Gráficos pesados em abas ocultas ainda executam efeitos e prejudicam o desempenho da rolagem. Correção: Retorne null de TabPanel inativo ou monte sob demanda na primeira ativação.
Componente "Deus" - Um mega-<Form> com 20 subpartes se torna mais difícil do que props. Correção: Divida em compostos FieldGroup, SelectField e DateField em vez de uma única exportação.
Estilização dentro de primitivos - Incorporar cores da marca em Tabs.Tab bloqueia aplicativos white-label. Correção: Aceite props style / textStyle ou um hook className para consumidores NativeWind.
Estado de acessibilidade não conectado - Abas sem accessibilityRole="tab" e estado selected confundem VoiceOver/TalkBack. Correção: Espelhe os papéis ARIA da web em Pressable de acordo com as orientações da plataforma.

Alternativas

Alternativa	Use Quando	Não Use Quando
Componentes compostos	Layout flexível de partes relacionadas que compartilham estado	Botão único autocontido sem filhos
Hook customizado + partes "burras"	Uma tela precisa de comportamento; sem API de filho compartilhado	Equipes externas compõem layouts de abas variados de sua biblioteca
Render props	O chamador possui a marcação inteiramente	A legibilidade do JSX importa - funções aninhadas ficam barulhentas
Arrays de configuração	Abas de ordem fixa de JSON de CMS	Designers reordenam elementos visuais por plataforma com frequência
Componente único + muitas props	≤3 variantes, sem flexibilidade estrutural	Lista de props excede ~8 props de layout opcionais
Headless + slots	Design system precisa de controle total de estilo	App interno com uma única linguagem visual

FAQs

O que torna um componente composto?

Um componente pai fornece estado compartilhado através de context (ou cloneElement em padrões mais antigos).
Os filhos são partes nomeadas compostas em JSX, não objetos de configuração opacos.
O chamador controla a estrutura e a ordem - a biblioteca não codifica um layout fixo.

Componentes compostos vs React Context - qual a diferença?

Componentes compostos são um padrão construído sobre context (ou estado com escopo).
Context bruto exporta um provedor e um hook; o composto envolve isso em subcomponentes ergonômicos.
Prefira compostos para APIs de design system; context bruto para tema ou autenticação em nível de aplicativo.

Painéis de abas inativos devem permanecer montados?

Desmonte quando os painéis executam efeitos pesados, visualizações de mapas ou players de vídeo.
Mantenha montado ao retornar para preservar a posição de rolagem ou a entrada do formulário.
Exponha unmountOnBlur?: boolean na raiz se ambos os casos de uso forem importantes.

Como tipar propriedades estáticas como Tabs.List?

Defina a função raiz, depois intercale com { List: typeof TabList; ... }.
Faça um cast uma vez ao anexar partes, ou construa um literal de objeto e afirme o tipo do namespace.
Re-exporte um único símbolo Tabs para que os consumidores importem um nome.

Armadilha: Por que todos os itens do acordeão re-renderizam ao alternar?

Um novo objeto de valor de context a cada renderização notifica todos os assinantes de useContext.
Memoize o valor do provedor e divida estado vs ações se as listas forem grandes.
Envolva os corpos dos itens em memo quando o conteúdo do painel for caro.

Componentes compostos podem funcionar com layouts do Expo Router?

Sim - um layout pode renderizar <Tabs> em torno de um <Slot /> para rotas aninhadas.
Abas baseadas em rotas ainda se beneficiam de gatilhos compostos que chamam router.push.
Veja Render Props & Slot Patterns para composição de slots.

Como compostos de campos de formulário se integram com bibliotecas de validação?

O FieldGroup raiz aceita error de fieldState.error?.message do React Hook Form.
Mantenha a lógica de validação fora do composto - ele apenas exibe o chrome de erro.
Passe onChangeText / value através de FieldGroup.Input sem alterações.

O `cloneElement` ainda é usado para componentes compostos?

Context é o padrão moderno - menos frágil do que alcançar props de filhos.
cloneElement aparece em bibliotecas legadas; novos design systems RN devem usar context.
O ref do React 19 como prop simplifica o encaminhamento sem cloneElement.

Quantos subcomponentes são muitos?

Se os consumidores usam rotineiramente apenas uma subparte, a API pode estar super-fatorada.
Mire em 3–6 partes por composto (Root, List, Trigger, Panel, Input).
Divida em múltiplos compostos ligados por hooks compartilhados quando os namespaces se tornam difíceis de gerenciar.

Armadilha: Colisões de `useId` entre servidores?

useId é por árvore React - seguro para IDs de itens de acordeão em dispositivos móveis.
Não persista a saída de useId no armazenamento; gere IDs de servidor separadamente para APIs.

Como as abas inferiores diferem das abas compostas?

Abas inferiores do React Navigation / Expo Router são navegadores com estado de rota.
Abas compostas são UI na tela para configurações, filtros ou etapas de assistente.
Use navegadores quando cada aba for uma rota; use compostos para alternância de painel local.

Posso encaminhar estilos para todas as partes?

function Tab({ index, children, style }: TabProps) {
  const { activeIndex, setActiveIndex } = useTabsContext();
  const active = activeIndex === index;
  return (
    <Pressable onPress={() => setActiveIndex(index)} style={[styles.tab, style]}>
      <Text>{children}</Text>
    </Pressable>
  );
}

Aceite style / textStyle opcionais em cada parte para substituições de marca.
Documente quais estilos se mesclam com os padrões em vez de substituí-los.

Como isso se relaciona com hooks customizados?

Extraia a lógica de estado para useTabsState() quando múltiplos componentes raiz precisam do mesmo comportamento.
O componente raiz composto chama o hook e passa o resultado para o context.
Veja Custom Hooks for UI Logic para a camada de hooks.

Raízes compostas devem renderizar um ScrollView?

Padrão para View - os chamadores envolvem em ScrollView quando o conteúdo transborda.
ScrollView embutido conflita com rolagem aninhada e layouts cientes do teclado.
Documente o comportamento de max-height para painéis de acordeão dentro de visualizações de rolagem pai.

Relacionados

Component Patterns Basics - pastas de recursos e divisões de apresentação
Custom Hooks for UI Logic - extraia o estado composto em hooks reutilizáveis
Render Props & Slot Patterns - alternativas de composição para árvores de navegação
Headless Components - compostos apenas de lógica sem estilo padrão
Typing Components & Props - tipagem de partes estáticas de namespace
Event Handling & Touchables - padrões de Pressable para gatilhos

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { createContext, useContext, useState, type ReactNode } from "react";
import { Pressable, Text, View } from "react-native";
 
interface TabsContextValue {
  activeIndex: number;
  setActiveIndex: (index: number) => void;
}
 
const TabsContext = createContext<TabsContextValue | null>(null);
 
function useTabsContext() {
  const ctx = useContext(TabsContext);
  if (!ctx) throw new Error("Tabs.* deve ser usado dentro de <Tabs>");
  return ctx;
}
 
function Tabs({ defaultIndex = 0, children }: { defaultIndex?: number; children: ReactNode }) {
  const [activeIndex, setActiveIndex] = useState(defaultIndex);
  return (
    <TabsContext.Provider value={{ activeIndex, setActiveIndex }}>
      <View>{children}</View>
    </TabsContext.Provider>
  );
}
 
function TabList({ children }: { children: ReactNode }) {
  return <View style={{ flexDirection: "row", gap: 8 }}>{children}</View>;
}
 
function Tab({ index, children }: { index: number; children: ReactNode }) {
  const { activeIndex, setActiveIndex } = useTabsContext();
  const active = activeIndex === index;
  return (
    <Pressable onPress={() => setActiveIndex(index)}>
      <Text style={{ fontWeight: active ? "700" : "400" }}>{children}</Text>
    </Pressable>
  );
}
 
function TabPanel({ index, children }: { index: number; children: ReactNode }) {
  const { activeIndex } = useTabsContext();
  if (activeIndex !== index) return null;
  return <View>{children}</View>;
}
 
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;
 
// Consumidor - reordene, omita ou reestilize partes livremente
export function SettingsScreen() {
  return (
    <Tabs defaultIndex={0}>
      <Tabs.List>
        <Tabs.Tab index={0}>Conta</Tabs.Tab>
        <Tabs.Tab index={1}>Privacidade</Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel index={0}>
        <Text>Configurações da conta</Text>
      </Tabs.Panel>
      <Tabs.Panel index={1}>
        <Text>Configurações de privacidade</Text>
      </Tabs.Panel>
    </Tabs>
  );
}

Quando usar isso:

Várias partes filhas precisam do mesmo estado do componente pai (aba ativa, seção aberta, erro de campo).
Listas de props como tabLabels, tabContents, onTabChange conflitam com layouts flexíveis.
Primitivos de design system devem permanecer sem estilo enquanto as equipes de produto compõem a estrutura.
Você deseja uma API que se pareça com JSX - <Card.Header> em vez de renderHeader().
Layouts móveis precisam reordenar elementos visuais (abas na parte inferior em celulares, na lateral em tablets) sem alterações na API.

Exemplo de Trabalho

import {
  createContext,
  useCallback,
  useContext,
  useId,
  useMemo,
  useState,
  type ReactNode,
} from "react";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
interface AccordionContextValue {
  openId: string | null;
  toggle: (id: string) => void;
}
 
const AccordionContext = createContext<AccordionContextValue | null>(null);
 
function useAccordion() {
  const ctx = useContext(AccordionContext);
  if (!ctx) throw new Error("Accordion.* deve ser usado dentro de <Accordion>");
  return ctx;
}
 
interface AccordionProps {
  children: ReactNode;
  defaultOpenId?: string | null;
}
 
function Accordion({ children, defaultOpenId = null }: AccordionProps) {
  const [openId, setOpenId] = useState<string | null>(defaultOpenId);
 
  const toggle = useCallback((id: string) => {
    setOpenId((current) => (current === id ? null : id));
  }, []);
 
  const value = useMemo(() => ({ openId, toggle }), [openId, toggle]);
 
  return (
    <AccordionContext.Provider value={value}>
      <View style={styles.accordion}>{children}</View>
    </AccordionContext.Provider>
  );
}
 
interface ItemProps {
  title: string;
  children: ReactNode;
}
 
function AccordionItem({ title, children }: ItemProps) {
  const id = useId();
  const { openId, toggle } = useAccordion();
  const open = openId === id;
 
  return (
    <View style={styles.item}>
      <Pressable
        onPress={() => toggle(id)}
        style={styles.trigger}
        accessibilityRole="button"
        accessibilityState={{ expanded: open }}
      >
        <Text style={styles.triggerText}>{title}</Text>
        <Text style={styles.chevron}>{open ? "▾" : "▸"}</Text>
      </Pressable>
      {open ? <View style={styles.panel}>{children}</View> : null}
    </View>
  );
}
 
interface FieldGroupContextValue {
  error?: string;
}
 
const FieldGroupContext = createContext<FieldGroupContextValue>({});
 
interface FieldGroupProps {
  label: string;
  error?: string;
  children: ReactNode;
}
 
function FieldGroup({ label, error, children }: FieldGroupProps) {
  const value = useMemo(() => ({ error }), [error]);
  return (
    <FieldGroupContext.Provider value={value}>
      <View style={styles.fieldGroup}>
        <Text style={styles.label}>{label}</Text>
        {children}
        {error ? <Text style={styles.error}>{error}</Text> : null}
      </View>
    </FieldGroupContext.Provider>
  );
}
 
function FieldInput(props: React.ComponentProps<typeof TextInput>) {
  const { error } = useContext(FieldGroupContext);
  return (
    <TextInput
      {...props}
      style={[styles.input, error && styles.inputError, props.style]}
      placeholderTextColor="#94a3b8"
    />
  );
}
 
FieldGroup.Input = FieldInput;
 
export default function ProfileFormScreen() {
  const [name, setName] = useState("");
  const nameError = name.length > 0 && name.length < 2 ? "O nome é muito curto" : undefined;
 
  return (
    <View style={styles.screen}>
      <Text style={styles.heading}>Perfil</Text>
 
      <Accordion defaultOpenId={null}>
        <AccordionItem title="Informações pessoais">
          <FieldGroup label="Nome de exibição" error={nameError}>
            <FieldGroup.Input
              value={name}
              onChangeText={setName}
              placeholder="Jane Doe"
              autoCapitalize="words"
            />
          </FieldGroup>
        </AccordionItem>
 
        <AccordionItem title="Notificações">
          <Text style={styles.body}>
            Preferências de push e e-mail ficam aqui. O acordeão mantém a tela
            curta em celulares pequenos.
          </Text>
        </AccordionItem>
      </Accordion>
    </View>
  );
}
 
Accordion.Item = AccordionItem;
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 16, backgroundColor: "#f8fafc", gap: 16 },
  heading: { fontSize: 24, fontWeight: "700", color: "#0f172a" },
  accordion: { gap: 8 },
  item: { backgroundColor: "#fff", borderRadius: 12, overflow: "hidden" },
  trigger: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    padding: 16,
  },
  triggerText: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  chevron: { fontSize: 14, color: "#64748b" },
  panel: { paddingHorizontal: 16, paddingBottom: 16, gap: 12 },
  fieldGroup: { gap: 6 },
  label: { fontSize: 14, fontWeight: "600", color: "#334155" },
  input: {
    borderWidth: 1,
    borderColor: "#cbd5e1",
    borderRadius: 10,
    padding: 12,
    fontSize: 16,
    backgroundColor: "#fff",
    color: "#0f172a",
  },
  inputError: { borderColor: "#dc2626" },
  error: { fontSize: 13, color: "#dc2626" },
  body: { fontSize: 15, color: "#475569", lineHeight: 22 },
});

O que isso demonstra:

Accordion possui openId; AccordionItem gera um useId() estável e lê a lógica de alternância compartilhada.
FieldGroup + FieldGroup.Input compartilham o estilo de erro sem passar error para cada prop de input.
Propriedades estáticas (Accordion.Item, FieldGroup.Input) expõem uma API de namespace descobrível.
Os consumidores controlam a ordem e a aninhamento - a cópia de notificações pode ficar ao lado do campo de nome sem alterações na API.
Valores de context são memoizados para evitar re-renderizar cada item quando um estado não relacionado muda.

Mergulho Profundo

Como Funciona

O componente composto raiz detém o estado (activeIndex, openId, variant) e o fornece via React.createContext.
Subcomponentes chamam useContext (envolvido em um hook customizado) para ler e atualizar o estado compartilhado.
Os filhos são compostos em JSX - o componente pai não mapeia sobre arrays de configuração para renderizar slots.
Atribuição estática (Tabs.List = TabList) anexa partes à exportação raiz para ergonomia de importação única.
O React 19 ainda reconcilia os filhos normalmente; as partes compostas são componentes de função comuns.
Lançar um erro quando o context é null falha rapidamente em desenvolvimento se uma parte for usada fora de seu provedor.

Blocos de Construção da API Composta

Peça	Responsabilidade	Nota RN
Raiz (`<Tabs>`)	Estado, provedor, shell de layout opcional	Frequentemente uma `View` com `gap` - sem `ScrollView` a menos que necessário
Lista / chrome (`Tabs.List`)	Agrupa gatilhos	Use `flexDirection: "row"` ou coluna para abas inferiores
Gatilho (`Tabs.Tab`)	`Pressable` + `accessibilityRole`	Marque `accessibilityState={{ selected: active }}`
Painel (`Tabs.Panel`)	Renderização condicional ou `display: "none"`	Desmonte painéis ocultos para economizar memória em telas pesadas
Input folha (`FieldGroup.Input`)	Encaminha refs/props para o primitivo	Espalhe props de `TextInput`; não codifique tipos de teclado

Estabilidade do Valor do Context

// Instável - novo objeto a cada renderização re-renderiza todos os consumidores
<TabsContext.Provider value={{ activeIndex, setActiveIndex }}>
 
// Estável - memoize; estabilize setters com useCallback na raiz
const value = useMemo(
  () => ({ activeIndex, setActiveIndex }),
  [activeIndex, setActiveIndex]
);

Apenas descendentes que leem um campo alterado re-renderizam quando o context atualiza.
Divida context "quente" e "frio" se necessário: TabsStateContext + TabsActionsContext para árvores grandes.
Para atualizações de alta frequência (controladores animados), prefira um hook ou ref em vez de context.

Notas de TypeScript

import type { ReactNode } from "react";
 
// Tipagem de namespace com partes estáticas
type TabsComponent = ((props: TabsProps) => JSX.Element) & {
  List: typeof TabList;
  Tab: typeof Tab;
  Panel: typeof TabPanel;
};
 
const Tabs = RootTabs as TabsComponent;
Tabs.List = TabList;
Tabs.Tab = Tab;
Tabs.Panel = TabPanel;
 
// Props discriminadas em itens - combinações inválidas falham em tempo de compilação
type FormFieldProps =
  | { kind: "text"; value: string; onChangeText: (t: string) => void }
  | { kind: "switch"; value: boolean; onValueChange: (v: boolean) => void };

Exporte hooks de context como useTabsContext - não exporte context bruto, a menos que seja para testes.
Tipifique partes estáticas com tipos de interseção para que Tabs.List tenha autocompletar no IDE.
Veja Typing Components & Props para uniões discriminadas em partes variantes.

Armadilhas

Guarda de provedor ausente - Usar Tabs.Tab fora de <Tabs> lê context null e se comporta silenciosamente de forma incorreta. Correção: Lance um erro em useTabsContext() com uma mensagem clara.
Valor de context instável - value={{ activeIndex, setActiveIndex }} inline re-renderiza cada consumidor a cada renderização do pai. Correção: Use useMemo para o valor; envolva setters em useCallback.
Abas baseadas em índice quebram na reordenação - index={2} codificado à mão muda quando o marketing insere uma aba. Correção: Use IDs de string ("account") como chaves internamente para as abas; mapeie para índice se necessário.
Montagem de todos os painéis de uma vez - Gráficos pesados em abas ocultas ainda executam efeitos e prejudicam o desempenho da rolagem. Correção: Retorne null de TabPanel inativo ou monte sob demanda na primeira ativação.
Componente "Deus" - Um mega-<Form> com 20 subpartes se torna mais difícil do que props. Correção: Divida em compostos FieldGroup, SelectField e DateField em vez de uma única exportação.
Estilização dentro de primitivos - Incorporar cores da marca em Tabs.Tab bloqueia aplicativos white-label. Correção: Aceite props style / textStyle ou um hook className para consumidores NativeWind.
Estado de acessibilidade não conectado - Abas sem accessibilityRole="tab" e estado selected confundem VoiceOver/TalkBack. Correção: Espelhe os papéis ARIA da web em Pressable de acordo com as orientações da plataforma.

Alternativas

Alternativa	Use Quando	Não Use Quando
Componentes compostos	Layout flexível de partes relacionadas que compartilham estado	Botão único autocontido sem filhos
Hook customizado + partes "burras"	Uma tela precisa de comportamento; sem API de filho compartilhado	Equipes externas compõem layouts de abas variados de sua biblioteca
Render props	O chamador possui a marcação inteiramente	A legibilidade do JSX importa - funções aninhadas ficam barulhentas
Arrays de configuração	Abas de ordem fixa de JSON de CMS	Designers reordenam elementos visuais por plataforma com frequência
Componente único + muitas props	≤3 variantes, sem flexibilidade estrutural	Lista de props excede ~8 props de layout opcionais
Headless + slots	Design system precisa de controle total de estilo	App interno com uma única linguagem visual

FAQs

O que torna um componente composto?

Um componente pai fornece estado compartilhado através de context (ou cloneElement em padrões mais antigos).
Os filhos são partes nomeadas compostas em JSX, não objetos de configuração opacos.
O chamador controla a estrutura e a ordem - a biblioteca não codifica um layout fixo.

Componentes compostos vs React Context - qual a diferença?

Componentes compostos são um padrão construído sobre context (ou estado com escopo).
Context bruto exporta um provedor e um hook; o composto envolve isso em subcomponentes ergonômicos.
Prefira compostos para APIs de design system; context bruto para tema ou autenticação em nível de aplicativo.

Painéis de abas inativos devem permanecer montados?

Desmonte quando os painéis executam efeitos pesados, visualizações de mapas ou players de vídeo.
Mantenha montado ao retornar para preservar a posição de rolagem ou a entrada do formulário.
Exponha unmountOnBlur?: boolean na raiz se ambos os casos de uso forem importantes.

Como tipar propriedades estáticas como Tabs.List?

Defina a função raiz, depois intercale com { List: typeof TabList; ... }.
Faça um cast uma vez ao anexar partes, ou construa um literal de objeto e afirme o tipo do namespace.
Re-exporte um único símbolo Tabs para que os consumidores importem um nome.

Armadilha: Por que todos os itens do acordeão re-renderizam ao alternar?

Um novo objeto de valor de context a cada renderização notifica todos os assinantes de useContext.
Memoize o valor do provedor e divida estado vs ações se as listas forem grandes.
Envolva os corpos dos itens em memo quando o conteúdo do painel for caro.

Componentes compostos podem funcionar com layouts do Expo Router?

Sim - um layout pode renderizar <Tabs> em torno de um <Slot /> para rotas aninhadas.
Abas baseadas em rotas ainda se beneficiam de gatilhos compostos que chamam router.push.
Veja Render Props & Slot Patterns para composição de slots.

Como compostos de campos de formulário se integram com bibliotecas de validação?

O FieldGroup raiz aceita error de fieldState.error?.message do React Hook Form.
Mantenha a lógica de validação fora do composto - ele apenas exibe o chrome de erro.
Passe onChangeText / value através de FieldGroup.Input sem alterações.

O `cloneElement` ainda é usado para componentes compostos?

Context é o padrão moderno - menos frágil do que alcançar props de filhos.
cloneElement aparece em bibliotecas legadas; novos design systems RN devem usar context.
O ref do React 19 como prop simplifica o encaminhamento sem cloneElement.

Quantos subcomponentes são muitos?

Se os consumidores usam rotineiramente apenas uma subparte, a API pode estar super-fatorada.
Mire em 3–6 partes por composto (Root, List, Trigger, Panel, Input).
Divida em múltiplos compostos ligados por hooks compartilhados quando os namespaces se tornam difíceis de gerenciar.

Armadilha: Colisões de `useId` entre servidores?

useId é por árvore React - seguro para IDs de itens de acordeão em dispositivos móveis.
Não persista a saída de useId no armazenamento; gere IDs de servidor separadamente para APIs.

Como as abas inferiores diferem das abas compostas?

Abas inferiores do React Navigation / Expo Router são navegadores com estado de rota.
Abas compostas são UI na tela para configurações, filtros ou etapas de assistente.
Use navegadores quando cada aba for uma rota; use compostos para alternância de painel local.

Posso encaminhar estilos para todas as partes?

function Tab({ index, children, style }: TabProps) {
  const { activeIndex, setActiveIndex } = useTabsContext();
  const active = activeIndex === index;
  return (
    <Pressable onPress={() => setActiveIndex(index)} style={[styles.tab, style]}>
      <Text>{children}</Text>
    </Pressable>
  );
}

Aceite style / textStyle opcionais em cada parte para substituições de marca.
Documente quais estilos se mesclam com os padrões em vez de substituí-los.

Como isso se relaciona com hooks customizados?

Extraia a lógica de estado para useTabsState() quando múltiplos componentes raiz precisam do mesmo comportamento.
O componente raiz composto chama o hook e passa o resultado para o context.
Veja Custom Hooks for UI Logic para a camada de hooks.

Raízes compostas devem renderizar um ScrollView?

Padrão para View - os chamadores envolvem em ScrollView quando o conteúdo transborda.
ScrollView embutido conflita com rolagem aninhada e layouts cientes do teclado.
Documente o comportamento de max-height para painéis de acordeão dentro de visualizações de rolagem pai.

Relacionados

Component Patterns Basics - pastas de recursos e divisões de apresentação
Custom Hooks for UI Logic - extraia o estado composto em hooks reutilizáveis
Render Props & Slot Patterns - alternativas de composição para árvores de navegação
Headless Components - compostos apenas de lógica sem estilo padrão
Typing Components & Props - tipagem de partes estáticas de namespace
Event Handling & Touchables - padrões de Pressable para gatilhos

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Componentes Compostos

Buscar na documentação

Componentes Compostos