Props são as entradas de um componente React. Um pai as passa como atributos no JSX, <UserCard name="Ada" online={true} />, e o filho as recebe como um único objeto, que você normalmente desestrutura nos parâmetros da função. As props permitem que um componente mostre dados diferentes a cada vez que você o usa.
O mesmo UserCard renderiza três pessoas diferentes. Repare no último: um atributo sem valor, online, significa online={true}. Adicione um quarto card com o seu nome e a sua função.
Passando e lendo props
Passe uma string entre aspas e qualquer outro valor entre chaves: números, booleanos, arrays, objetos, funções e até JSX.
<Product
title="Desk lamp"
price={39.5}
inStock={false}
tags={['light', 'office']}
seller={{ name: 'Lumen', rating: 4.8 }}
/>
O React junta todos os atributos em um objeto e o passa como primeiro argumento do componente. Você pode lê-lo como props ou extrair os campos de que precisa direto na lista de parâmetros:
function Product(props) {
return <h3>{props.title}</h3>;
}
function Product({ title, price, seller }) {
return <h3>{title}, ${price} from {seller.name}</h3>;
}
As duas versões recebem o mesmo objeto. A desestruturação é o estilo comum porque assim a assinatura da função lista exatamente quais props o componente usa.
Valores padrão
Dê um padrão a uma prop com o valor padrão da desestruturação do JavaScript, = value. Ele vale quando o pai omite a prop ou passa undefined. Não vale para null, 0, false ou '', que são valores de verdade.
Os três primeiros botões caem nos padrões onde uma prop está ausente ou é undefined. O último passa null, então size realmente é null, e a busca não encontra padding. Troque size={null} por size="small" para corrigir.
Código mais antigo define padrões com uma propriedade estática, Button.defaultProps = { size: 'medium' }. O React 19 removeu defaultProps para componentes de função: o JSX o ignora em uma função, sem aviso. Ele ainda funciona em componentes de classe. Use valores padrão na desestruturação.
Passando funções como props
Os dados descem: um pai passa props para os filhos, nunca o contrário. Quando um filho precisa avisar o pai de que algo aconteceu, o pai passa uma função, e o filho a chama. Por convenção essas props se chamam onSomething.
Rating não guarda nada. Ele mostra o value que recebe e informa os cliques por meio de onRate. O estado mora em App, que o passa de volta para baixo. Passe onRate={setRating} diretamente em vez de handleRate e continua funcionando: um setter também é uma função. Mover o estado para um pai comum assim se chama elevar o estado.
Espalhando props
Quando você já tem um objeto cujas chaves batem com as props de um componente, espalhe-o com {...object} em vez de escrever cada atributo. A sintaxe rest faz o contrário na lista de parâmetros: pega algumas props pelo nome, junta todo o resto e repassa.
O segundo avatar espalha person e depois define color: quando a mesma prop aparece duas vezes, a última vence, então coloque as sobrescritas depois do spread. TextField fica com label para si e passa type, placeholder e maxLength direto para o <input>. Use o spread em wrappers como este; no resto, listar as props explicitamente deixa mais fácil ver o que um componente recebe.
Props são somente leitura
Um componente nunca deve mudar as próprias props. Elas pertencem ao pai, e o mesmo objeto pode ser compartilhado. Trate-as como argumentos de função que você não pode reatribuir:
function Counter({ count }) {
count = count + 1; // wrong: changes a local copy, the parent never sees it
return <p>{count}</p>;
}
function Profile(props) {
props.name = 'Someone else'; // wrong: in development React freezes props, so this throws a TypeError
return <p>{props.name}</p>;
}
As props ainda mudam com o tempo. Quando o pai renderiza de novo com novos valores, o filho recebe um novo objeto de props e renderiza com ele:
Temperature nunca muda celsius. Ele calcula fahrenheit a partir dele em toda renderização. Arraste o slider e o estado do pai muda, então o filho recebe uma nova prop. Se um filho precisa de um valor que ele mesmo possa mudar, esse valor é estado, não prop.
Props vs estado
Props e estado são valores JavaScript comuns que afetam o que um componente renderiza, e uma mudança em qualquer um deles renderiza o componente de novo. A diferença é quem é o dono do valor.
| Props | Estado | |
|---|---|---|
| Vem de | O pai, como atributos JSX | O próprio componente, de useState ou useReducer |
| O componente pode mudar | Não, é somente leitura | Sim, pelo setter |
| Uso típico | Configurar um componente: um rótulo, um tamanho, os dados a mostrar | Lembrar algo que muda: o texto de um input, um menu aberto |
Muitas vezes o mesmo valor é as duas coisas. No exemplo da temperatura acima, celsius é estado em App e prop em Temperature. O dono o guarda como estado e o passa para baixo como prop, junto com uma função para mudá-lo quando um filho precisa disso.
Uma prop pode guardar qualquer valor, inclusive JSX e componentes. Passar um elemento como icon={<StarIcon />} permite que um pai preencha um espaço em um filho, a mesma ideia de children com um nome que você escolhe.
A prop children
O que você coloca entre a tag de abertura e a de fechamento de um componente chega como uma prop chamada children. É assim que você constrói wrappers como cards, painéis e layouts que não conhecem o conteúdo de antemão:
A página sobre children trata de passar vários espaços e de trabalhar com children com segurança.
Keys não são props
key parece um atributo, mas o React a guarda para si para associar os itens de lista entre renderizações. O componente nunca a recebe:
O console mostra props.key como undefined e props.id com o valor real. Quando um filho precisa do identificador, passe-o uma segunda vez com outro nome, como id faz aqui. Um build de desenvolvimento também avisa quando você lê props.key; a prévia roda como um build de produção, então você só vê o undefined.
Perguntas frequentes
O que são props no React?
Props (abreviação de properties, propriedades) são os argumentos de um componente. Um pai as passa como atributos JSX, <Avatar size={48} />, e o filho as recebe como um único objeto, normalmente desestruturado: function Avatar({ size }).
Como defino um valor padrão para uma prop?
Use um valor padrão na desestruturação: function Button({ size = 'medium' }). O padrão vale quando a prop está ausente ou é undefined. O React 19 removeu defaultProps para componentes de função; componentes de classe ainda o suportam.
Um componente filho pode mudar as próprias props?
Não. Props são somente leitura. Para mudar o que um filho mostra, o pai passa novas props; para deixar o filho pedir uma mudança, o pai passa uma função como onChange e o filho a chama.
Qual é a diferença entre props e estado?
Props vêm do pai e o filho não pode mudá-las. O estado pertence ao próprio componente e muda pelo setter dele. Muitas vezes um valor é estado em um pai e prop nos filhos dele.
Por que props.key é undefined?
key (como ref em versões antigas do React) é usada pelo próprio React para acompanhar itens de lista e não é passada para o componente. Se o filho precisa do valor, passe-o de novo com outro nome, por exemplo <Row key={id} id={id} />.
