# QR Code

> A real, scannable QR code made on the device, as ink on a white tile in both themes, with its quiet zone built in.

- Name: `qr-code`
- Status: beta
- Categories: data, display
- File: the install writes `qr-code.tsx` to your `ui` alias, `@/components/ui` by default.
- Gallery: https://arbokui.com/components/qr-code
- Registry item: https://arbokui.com/r/qr-code.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/qr-code
   ```

## Use it for

- A code people scan with a phone: a check-in, a join link, an event pass, a printed poster.
- Pass value, usually a link, and aria-label, like 'Check-in code for the Workshop'.
- Always pair it with another way in, like a short code to type or check-in by name. Nothing should be camera-only.
- Pass className='w-full' for a poster. It scales as vector.
- Use encodeQRCode(value) for the modules alone, to draw them some other way.

## Avoid it for

- A link people can click on the same screen. Show the link.
- Long text, like a whole message. A long value makes a dense code that is hard to scan. Link to the text instead.
- Secrets. Anyone who can see the code can read it.

## Props

- `value`: `string`. Required. What the code holds, usually a link. It is encoded as UTF-8 bytes.
- `aria-label`: `string`. Required. Names the code for screen readers, like 'Ava Clarke's guest pass'.
- `size`: `"sm" | "md" | "lg"`. Default `"md"`. The most it draws: 120, 160, or 240px. Modules snap to whole pixels, so edges stay crisp.
- `level`: `"L" | "M" | "Q" | "H"`. Default `"M"`. The least error correction. It rises for free while the data still fits the same size.
- `margin`: `number`. Default `4`. The white quiet zone around the code, in modules. 4 is the standard's minimum.
- `className`: `string`. Extra classes. Later classes win, so className='w-full max-w-none' fills a poster.

## Accessibility

- Renders an \<svg> with role="img", named by aria-label. TypeScript requires it.
- The code is ink on a white tile in light and dark, since many phone cameras cannot read a light code on dark.
- A value too long for any code shows an empty dashed tile, and its name says so.
- Screen readers cannot read the code itself. Put the link or a short code beside it as text.

## Examples

### A pass, named for screen readers

```tsx
<QRCode value="https://example.com/p/ava-clarke-7q2k" aria-label="Ava Clarke's guest pass" />
```

### With another way in

```tsx
<div className="flex items-center gap-4">
  <QRCode value="https://example.com/check-in/4821" aria-label="Check-in code for the Workshop" size="sm" />
  <p>Or type the code 4821 at the door.</p>
</div>
```

### For a poster

```tsx
<QRCode value="https://example.com/join" aria-label="Join the team" level="H" className="w-full max-w-none" />
```