# QRCode

Um texto que a câmera do outro lê: o link de consulta da nota, o Pix de uma
cobrança, o endereço de um cardápio.

O desenho é um SVG gerado aqui, sem biblioteca: o codificador segue a ISO/IEC
18004 inteira, com as versões 1 a 40, os modos numérico, alfanumérico e byte
(em UTF-8), a correção Reed-Solomon e a escolha entre as oito máscaras pela
penalidade da norma. A versão é a menor em que o texto cabe, então o quadrado
tem tantos módulos quanto o texto pede, e nenhum a mais.

```tsx
<QRCode value={linkDaNota} label="QR Code para consultar a nota 4813" />
```

`label` é obrigatório. A peça é uma imagem (`role="img"`), e o conteúdo cru
não serve de nome: um leitor de tela que soletra
`00020126580014br.gov.bcb.pix…` não diz nada. O nome diz para que o código
serve.

## Cores e margem

**Código lido por máquina é sempre escuro sobre claro, em qualquer tema.** Os
módulos saem em `code-ink` (quase preto) e o fundo em `code-paper` (branco), e
os dois têm o mesmo valor no tema claro, no escuro e em qualquer tema de
cliente. A ISO/IEC 18004 aceita o reflexo invertido, com módulo claro sobre
fundo escuro, e a câmera do sistema até lê; uma parte dos leitores e dos apps
de banco não lê. Para um Pix, isso é pagamento que não acontece, e nada na
tela avisa.

Por isso o par não é papel de tema: ele mora na escala, fora de
`[data-rc-theme]`, e um tema não precisa declará-lo nem consegue invertê-lo
sem querer. A guarda de contraste mede a tinta sobre o papel a 15:1 no
mínimo (a casa dá 19,47:1) e confere que a tinta é a mais escura dos dois.
Não envolva a peça num `RivoProvider` claro para o código ler: ela já lê.

No tema escuro o papel vira uma **placa branca de canto arredondado** dentro
do cartão escuro. A placa inclui a **margem de silêncio de 4 módulos** que a
norma pede: é ela que separa o código do que está em volta, e sem ela a câmera
não acha as três quinas. Por isso a placa não tem respiro próprio, e não deve
ganhar `padding` de fora.

As mesmas cores servem a quem desenha outro código lido por máquina, como um
código de barras: `fill-code-ink`, `bg-code-paper` e `text-code-ink`.

## Correção de erro

`level` escolhe quanto do símbolo pode se perder sem que o texto se perca:
`L` recupera 7%, `M` 15% (o padrão), `Q` 25% e `H` 30%. Nível mais alto pede
mais módulos para o mesmo texto, e por isso quadrados maiores.

Use `Q` ou `H` para o que vai ser impresso, amassado ou lido de longe, e `M`
para a tela.

## Tamanho

`size` é o lado em px, com a margem incluída. Cada módulo precisa de ao menos
2px de tela para a câmera separar um do outro: o Pix de uma cobrança (versão 8
no nível M, 57 módulos com a margem) pede 160px ou mais. Um
texto longo com `size` pequeno desenha certo e não lê.

## Com logo

`logo` põe uma marca no centro, e **só vale com `level="H"`**. Os módulos
embaixo da marca são apagados de verdade (o papel aparece por trás dela, e a
marca herda a tinta como `currentColor`), e só
o nível H recupera essa perda com folga. Com `logo` e sem `level`, a peça já
nasce em H; com `logo` e outro nível, a marca não aparece, e o console diz por
quê.

```tsx
<QRCode value={linkDaNota} label="QR Code para consultar a nota 4813" logo={<img src="/marca.svg" alt="" />} />
```

Sem `value`, o quadrado guarda o lugar com um traço pontilhado sobre a
superfície, sem módulo nenhum, para a tela não pular quando o texto chegar. Não
é a placa branca: no tema escuro um quadrado branco vazio parece um código que
falhou ao desenhar.

## Texto que não cabe

A versão 40 guarda 2953 bytes no nível L e 1273 no H. Texto maior não cabe em
QR nenhum, e a peça **não derruba a tela** por isso: no lugar do código ela
desenha o mesmo quadrado pontilhado com o aviso de `labels.tooLong`, o nome da
imagem ganha o aviso junto, e o console avisa em desenvolvimento. A saída é
encurtar o texto, trocar por um link que leve a ele ou baixar o nível.

```tsx
<QRCode value={texto} label="QR Code do cardápio" labels={{ tooLong: 'Cardápio longo demais para o QR.' }} />
```

## Partes

`classNames` alcança `code` (o `svg`) e `logo` (a caixa do centro).

## Quando não usar

- **Para o Pix de uma cobrança**, use `PixCode`: ele junta este código, o copia
  e cola com o botão de copiar, o valor e o recebedor, e confere o CRC.
- **Para um texto que a pessoa precisa ler ou digitar**, como a chave de
  acesso que vai para o campo de outro sistema, use `Code` com um `Clipboard`
  ao lado. O QR só serve a quem tem uma câmera apontada para a tela.
- **Na tela de quem vai usar o texto.** Ninguém aponta a câmera para o próprio
  celular: se a pessoa já está no aparelho, o link é um `Link` e o código é um
  `Clipboard`.

## No React Native

Traduz, no caminho `@rivocode/ui-native/chart`: o código é desenhado com o `react-native-svg`, peer da raiz, e mora com o gráfico pelo peso. Desenhar com `View` custaria centenas de caixas por código, uma por trecho de módulos escuros, e o Pix de uma cobrança passa de dois mil módulos.

**O codificador é o mesmo dos dois lados, linha por linha**: ele mora em `src/shared/` e atravessa por espelho, então versão, máscara e correção de erro não divergem. O teste do nativo rasteriza o caminho que a peça desenha e o decodifica de volta, como o do web.

As cores **não** saem do tema: os módulos são `tokens.code["code-ink"]` e o papel `tokens.code["code-paper"]`, escuro sobre claro nos dois esquemas, numa placa de canto arredondado. Não passam pelo CSS do app nem pelo `colors` do `RivoProvider`, então nenhum `@theme` de cliente inverte o código sem querer. `level`, `size` e `logo` têm o mesmo contrato do web: com `logo` o nível nasce H, e com outro nível a marca não aparece. Das partes do web, só `logo` porta: `code` é o `Svg`, e o `react-native-svg` não recebe classe; o resto veste pela raiz.

```tsx
import { QRCode } from '@rivocode/ui-native/chart'

<QRCode value={link} label="QR Code para acompanhar o pedido 4813" />
```

## Importação

```tsx
import { QRCode } from '@rivocode/ui'
```

## Exemplos

### Link de consulta da nota

```tsx
import { QRCode } from '@rivocode/ui'

const LINK_DA_NOTA = 'https://nfse.rivocode.com.br/consulta/35240612345678000199550010000048131234567890'

export function InvoiceLink() {
  return <QRCode value={LINK_DA_NOTA} label="QR Code para consultar a nota 4813" />
}
```

### Com a marca no centro

```tsx
import { QRCode } from '@rivocode/ui'

const LINK_DA_NOTA = 'https://nfse.rivocode.com.br/consulta/35240612345678000199550010000048131234567890'

export function WithLogo() {
  return (
    <QRCode
      value={LINK_DA_NOTA}
      label="QR Code para consultar a nota 4813"
      size={200}
      logo={<span className="font-display text-sm font-semibold">R</span>}
    />
  )
}
```

### Solto na página, e mais robusto

```tsx
import { QRCode } from '@rivocode/ui'

const LINK_DA_NOTA = 'https://nfse.rivocode.com.br/consulta/35240612345678000199550010000048131234567890'

export function OnPage() {
  return (
    <div className="bg-bg p-4">
      <QRCode value={LINK_DA_NOTA} label="QR Code para consultar a nota 4813" level="Q" size={128} />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | sim |  | - | O nome que o leitor de tela ouve, dizendo para que o codigo serve, e nao o conteudo cru. |
| `value` | `string` | sim |  | - | O texto que o codigo carrega: link, copia e cola do Pix, chave de acesso. |
| `classNames` | `Partial<Record<"code" \| "logo", string>>` |  |  | - | Classe por parte: `code` (o svg) e `logo`. |
| `labels` | `{ tooLong?: string \| undefined; }` |  |  | - | Os textos da peca. |
| `level` | `"H" \| "L" \| "M" \| "Q"` |  |  | - | A correcao de erro, de `L` (recupera 7% do simbolo) a `H` (30%), com `M` (15%) sem logo e `H` com logo. |
| `logo` | `ReactNode` |  |  | - | A marca no centro: os modulos embaixo dela sao apagados. |
| `size` | `number` |  | `160` | - | O lado do quadrado em px, com a margem de silencio incluida. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioPlayer](/componentes/audio-player.md)
- [Code](/componentes/code.md)
- [EventCalendar](/componentes/event-calendar.md)
- [Gantt](/componentes/gantt.md)
- [Kanban](/componentes/kanban.md)
- [PixCode](/componentes/pix-code.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
