# React

O `@unicep/react` traz o hook `useCep`, para React 18 ou mais novo.

```bash
npm install @unicep/react
```

```bash
pnpm add @unicep/react
```

```bash
yarn add @unicep/react
```

```bash
bun add @unicep/react
```

O `@unicep/core` é instalado junto.

## Uso

```tsx
import { useState } from 'react';
import { useCep } from '@unicep/react';

export function CampoCep() {
  const [valor, setValor] = useState('');
  const { data, error, isLoading } = useCep(valor);

  return (
    <>
      <input value={valor} onChange={(e) => setValor(e.target.value)} placeholder="00000-000" />
      {isLoading && <p>Buscando…</p>}
      {error && <p>{error.message}</p>}
      {data && (
        <p>
          {data.street}, {data.neighborhood} - {data.city}/{data.state}
        </p>
      )}
    </>
  );
}
```

O hook só busca quando o valor é um CEP válido (com ou sem hífen), então dá para ligá-lo direto a um campo de texto. Se o CEP mudar, o resultado anterior some e a requisição em andamento é cancelada.

## API

```ts
useCep(cep: string | null | undefined, options?: {
  unicep?: Unicep;    // padrão: instância compartilhada com todos os providers embutidos
  enabled?: boolean;  // false pausa as consultas, padrão true
}): {
  data: Address | undefined;
  error: Error | undefined;
  isLoading: boolean; // true enquanto a consulta do CEP válido atual está em andamento
}
```

O `error` é um dos [erros da unicep](/docs/errors), como `CepNotFoundError` ou
`AllProvidersFailedError`.

## Providers e opções próprias

```tsx
import { Unicep, viaCep, brasilApi } from '@unicep/core';

// Crie uma vez, fora do componente, para não perder o estado dos circuit breakers.
const unicep = new Unicep({
  providers: [viaCep(), brasilApi()],
  timeoutMs: 3000,
  cache: {},
});

const { data } = useCep(valor, { unicep });
```

Todas as opções estão em [Providers](/docs/providers) e no [Core](/docs/core).