React Top-Level API

React é o ponto de entrada da biblioteca React. Se você carrega o React a partir de uma tag <script>, estas APIs top-level estarão disponíveis no React global. Se você usa ES6 com npm, você pode escrever import React from 'react'. Se você usa ES5 com npm, você pode escrever var React = require('react').

Visão Geral

Componentes

Os componentes React permitem que você divida a UI em pedaços independentes e reutilizáveis para pensar em cada pedaço isoladamente. Os componentes em React podem ser definidos ao estender React.Component ou React.PureComponent.

• React.Component
• React.PureComponent

Se você não utiliza classes do ES6, você pode usar o módulo create-react-class. Veja Usando React sem ES6 para mais informações.

Os componentes em React também podem ser definidos como funções que podem ser envoltas:

• React.memo

Criando Elementos em React

Nós recomendamos utilizar o JSX para descrever como sua UI deve se parecer. Cada elemento JSX é somente uma maneira alternativa de utilizar o React.createElement(). Em geral você não vai utilizar os métodos seguintes caso esteja usando JSX.

• createElement()
• createFactory()

Veja Usando React sem JSX para mais informações.

Transformando Elementos

O React provê várias APIs para manipulação de elementos:

• cloneElement()
• isValidElement()
• React.Children

Fragments

O React também provê um componente para que você possa renderizar múltiplos elementos sem a necessidade de criar outro elemento que os envolva.

• React.Fragment

Refs

• React.createRef
• React.forwardRef

Suspense

O Suspense permite que componentes “esperem” por algo antes de renderizar. Atualmente, o Suspense suporta somente uma finalidade: carregar componentes dinamicamente com React.lazy. Futuramente, ele prestará suporte para outras finalidades, como busca de dados.

• React.lazy
• React.Suspense

Transitions

Transitions are a new concurrent feature introduced in React 18. They allow you to mark updates as transitions, which tells React that they can be interrupted and avoid going back to Suspense fallbacks for already visible content.

• React.startTransition
• React.useTransition

Hooks

Os Hooks são uma novidade no React 16.8. Eles permitem que você utilize o estado (state) e outras funcionalidades do React sem ter que escrever uma classe para isso. Os Hooks possuem uma seção dedicada na documentação e uma referência da API separada:

• Hooks Básicos

  • useState
  • useEffect
  • useContext

• Hooks Adicionais

  • useReducer
  • useCallback
  • useMemo
  • useRef
  • useImperativeHandle
  • useLayoutEffect
  • useDebugValue
  • useDeferredValue
  • useTransition
  • useId

• Library Hooks

  • useSyncExternalStore
  • useInsertionEffect

Referência

React.Component

React.Component é a classe base para componentes React quando eles são definidos usando classes ES6:

class Greeting extends React.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

Consulte a referência da API para React.Component para ver uma lista de métodos e propriedades relacionadas à classe base React.Component.

React.PureComponent

React.PureComponent é similar a React.Component. A diferença entre eles é que o React.Component não implementa o shouldComponentUpdate(), enquanto o React.PureComponent a implementa com uma comparação superficial de props e state.

Se o método render() do seu componente React renderiza o mesmo resultado dados os mesmos props e state, você pode usar React.PureComponent para um aumento no desempenho em alguns casos.

Nota

O shouldComponentUpdate() do React.PureComponent apenas compara superficialmente os objetos. Se estes contiverem estruturas de dados complexas, podem produzir falsos negativos para diferenças mais profundas. Apenas estenda PureComponent quando você espera ter propriedades e estados simples, ou use forceUpdate() quando você souber que estruturas de dados profundas foram alteradas. Ou considere usar objetos imutáveis para facilitar comparações rápidas de dados aninhados.

Além disso, o método shouldComponentUpdate() do React.PureComponent pula atualizações de prop para toda a subárvore do componente. Esteja certo de que todos seus componentes que descendem dele também são “puros”.

React.memo

const MyComponent = React.memo(function MyComponent(props) {
  /* renderize usando props */
});

O React.memo é um higher order component.

Se seu componente renderiza o mesmo resultado dados os mesmos props, você pode envolver nele uma chamada para React.memo para um aumento no desempenho em alguns casos, através da memoização do resultado. Isto significa que o React vai pular a renderização do componente e reutilizar o último resultado renderizado.

React.memo verifica apenas as alterações de prop. Se o seu componente de função envolvido em React.memo tiver um useState, useReducer ou useContext Hook em sua implementação, ele ainda será renderizado quando o estado ou o contexto mudar.

Por padrão, ele irá comparar apenas superficialmente os objetos nos props. Se você quiser controle sob a comparação, você também pode prover uma função customizada de comparação como segundo argumento.

function MyComponent(props) {
  /* renderize usando props */
}
function areEqual(prevProps, nextProps) {
  /*
  se prevProps e nextProps renderizam o mesmo resultado,
  retorne true.
  caso contrário, retorne false.
  */
}
export default React.memo(MyComponent, areEqual);

Este método existe somente como uma otimização de performance. Não conte com ele para “prevenir” uma renderização, pois isso pode levar a bugs.

Nota

Ao contrário do método shouldComponentUpdate() de class components, a função areEqual retorna true se os props são iguais e false se os props não são iguais. É o inverso de shouldComponentUpdate.

createElement()

React.createElement(
  type,
  [props],
  [...children]
)

Cria e retorna um novo elemento React do tipo determinado. O argumento type pode ser uma string contendo a tag name (como, por exemplo, 'div' ou 'span'), um componente React (uma classe ou uma função), ou um React fragment.

Código escrito utilizando JSX será convertido para utilizar React.createElement(). Você tipicamente não invocará React.createElement() diretamente se você estiver usando JSX. Veja React sem JSX para aprender mais.

cloneElement()

React.cloneElement(
  element,
  [config],
  [...children]
)

Clona e retorna um novo elemento React usando element como ponto de partida. config deve conter todos os novos adereços, key ou ref. O elemento resultante terá os props do elemento original, com os novos props mesclados superficialmente. Novos elementos filhos substituirão os existentes. key e ref do elemento original serão preservados se não houver key e ref presentes na config.

React.cloneElement() é quase equivalente a:

<element.type {...element.props} {...props}>{children}</element.type>

No entanto, ele também preserva refs. Isto significa que se você possui um elemento filho com um ref nele, você não o roubará acidentalmente do seu antecessor. Você terá o mesmo ref ligado ao seu novo elemento. A nova ref ou key irá substituir as antigas, se houver.

Esta API foi introduzida como uma reposição ao React.addons.cloneWithProps(), que foi descontinuado.

createFactory()

React.createFactory(type)

Retorna uma função que produz elementos React do tipo determinado. Assim como em React.createElement(), o argumento type pode ser uma string contendo o tag name (como, por exemplo, 'div' ou 'span'), um componente React (uma classe ou uma função), ou um React fragment.

Este helper é considerado legado, e nós encorajamos você a utilizar JSX ou React.createElement() diretamente como alternativa.

Em geral você não invocará React.createFactory() diretamente se estiver utilizando JSX. Veja React sem JSX para aprender mais.

isValidElement()

React.isValidElement(object)

Verifica se o objeto é um elemento React. Retorna true ou false.

React.Children

React.Children provê utilitários para lidar com a estrutura de dados opaca this.props.children.

React.Children.map

React.Children.map(children, function[(thisArg)])

Invoca uma função em cada elemento filho imediato contido em children com this definido para thisArg. Se children for um array, a função será chamada para cada filho no array. Se children for null ou undefined, este método retornará null ou undefined ao invés de um array.

Nota

Se children for um Fragment ele será tratado como um elemento filho único.

React.Children.forEach

React.Children.forEach(children, function[(thisArg)])

Igual a React.Children.map(), mas não retorna um array.

React.Children.count

React.Children.count(children)

Retorna o número total de componentes em children, igual ao número de vezes que o callback passado para map ou forEach seria invocado.

React.Children.only

React.Children.only(children)

Verifica que children possui apenas um elemento filho (um elemento React) e o retorna. Caso contrário, este método lança um erro.

Nota

O React.Children.only() não aceita o valor retornado de React.Children.map() pois este é um array ao invés de um elemento React.

React.Children.toArray

React.Children.toArray(children)

Retorna a estrutura de dados opaca children como um flat array com as chaves atribuídas a cada elemento filho. Útil se você deseja manipular coleções de elementos filhos em seus métodos de renderização, especialmente se você quiser reordenar ou repartir this.props.children antes de repassá-los.

Nota

React.Children.toArray() altera keys para preservar a semântica de arrays aninhados quando realizando o flatten de listas de elementos filho. Isto é, toArray prefixa cada key no array retornado, de tal modo que o key de cada elemento possui o escopo do array que o contém.

React.Fragment

O componente React.Fragment permite que você retorne múltiplos elementos num método render() sem precisar criar um elemento DOM adicional:

render() {
  return (
    <React.Fragment>
      Some text.
      <h2>A heading</h2>
    </React.Fragment>
  );
}

Você também pode usar ele com a forma abreviada <></>. Para mais informações, veja React v16.2.0: Suporte Melhorado para Fragments.

React.createRef

React.createRef cria uma ref que pode ser anexada a elementos React através do atributo ref.

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.inputRef = React.createRef();  }

  render() {
    return <input type="text" ref={this.inputRef} />;  }

  componentDidMount() {
    this.inputRef.current.focus();  }
}

React.forwardRef

React.forwardRef cria um componente React que encaminha o atributo ref que ele recebe para outro componente abaixo na árvore. Esta técnica não é muito comum, mas é particularmente útil nos dois cenários:

• Encaminhando refs para componentes DOM
• Encaminhando refs em higher-order-components

React.forwardRef aceita uma função de renderização como argumento. React chamará esta função com props e ref como seus dois argumentos. Esta função deve retornar um React node.

const FancyButton = React.forwardRef((props, ref) => (  <button ref={ref} className="FancyButton">    {props.children}
  </button>
));

// You can now get a ref directly to the DOM button:
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

No exemplo acima, React passa o ref dado para o elemento <FancyButton ref={ref}> como o segundo argumento para a função de renderização dentro da chamada React.forwardRef.

Como resultado, após React anexar o ref, ref.current irá apontar diretamente para a instância do elemento DOM <button>

Para mais informações, veja encaminhando refs.

React.lazy

React.lazy() permite que você defina um componente que é carregado dinamicamente. Isto ajuda a reduzir o tamanho do bundle, retardando o carregamento de componentes que não são utilizados durante a renderização inicial.

Você pode aprender como utilizar isto em nossa documentação de code splitting. Você pode também querer ver este artigo explicando como utilizar mais detalhadamente.

// Este componente é carregado dinamicamente
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Note que renderizar componentes lazy requer que exista um componente <React.Suspense> num nível mais alto da árvore de renderização. É assim que você especifica um indicador de carregamento.

React.Suspense

React.Suspense permite que você especifique o indicador de carregamento no caso de alguns componentes na árvore abaixo dele ainda não estarem prontos para renderizar. No futuro, planejamos permitir que Suspense lide com mais cenários, como busca de dados. Você pode ler sobre isso em nosso roteiro.

Hoje, carregamento lento de componentes é o único caso de uso suportado por <React.Suspense>:

// Este componente é carregado dinamicamente
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Mostra <Spinner> enquanto OtherComponent carrega
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Isto está documentado em nosso guia para code splitting. Note que componentes lazy podem estar em níveis profundos dentro da árvore de Suspense — ele não precisa envolver cada um deles. A melhor prática é colocar <Suspense> onde você quer ver um indicador de carregamento, mas utilizar lazy() onde você quiser realizar code splitting.

Nota

Para o conteúdo que já é mostrado ao usuário, voltar para um indicador de carregamento pode ser desorientador. Às vezes, é melhor mostrar a IU “antiga” enquanto a nova IU está sendo preparada. Para fazer isso, você pode usar as novas APIs de transição startTransition e useTransition para marcar atualizações como transições e evitar fallbacks inesperados.

React.Suspense na renderização do lado do servidor

Durante a renderização do lado do servidor, os limites de suspensão permitem que você elimine seu aplicativo em partes menores por meio da suspensão. Quando um componente é suspenso, agendamos uma tarefa de baixa prioridade para renderizar o fallback do limite Suspense mais próximo. Se o componente for suspenso antes de liberarmos o fallback, enviaremos o conteúdo real e descartaremos o fallback.

React.Suspense durante a hidratação

Os limites suspensos dependem de seus limites pais serem hidratados antes que possam se hidratar, mas eles podem se hidratar independentemente dos limites irmãos. Eventos em um limite antes de ser hidratado farão com que o limite seja hidratado com uma prioridade mais alta do que os limites vizinhos. Leia mais

React.startTransition

React.startTransition(callback)

React.startTransition permite marcar atualizações dentro do callback fornecido como transições. Este método é projetado para ser usado quando React.useTransition não está disponível.

Nota:

Atualizações em uma transição dão lugar a atualizações mais urgentes, como cliques.

As atualizações em uma transição não mostrarão um fallback para conteúdo ressuspenso, permitindo que o usuário continue interagindo enquanto renderiza a atualização.

React.startTransition não fornece um sinalizador isPending. Para acompanhar o status pendente de uma transição, consulte React.useTransition.