Kappa / QR Code

<script setup lang="ts">
import { QrCode } from "@dicehub/kappa/components/qr-code";
</script>

<template>
  <QrCode.Root
    id="quick-link-code"
    default-value="https://example.com/start"
    :pixel-size="6"
  >
    <QrCode.Frame role="img" aria-label="QR code for the getting started guide">
      <QrCode.Pattern />
    </QrCode.Frame>
  </QrCode.Root>
</template>

Installation

QR Code is part of the main Kappa package and uses Ark UI's reactive generator.

Barrel

import { QrCode } from "@dicehub/kappa";

Granular

import { QrCode } from "@dicehub/kappa/components/qr-code";

Usage

Compose the generated pattern inside a labelled SVG frame.

Scan to open the event page

<script setup lang="ts">
import { QrCode } from "@dicehub/kappa/components/qr-code";
</script>

<template>
  <figure class="qr-code-example">
    <QrCode.Root
      id="event-code"
      default-value="https://example.com/events/meetup"
      :pixel-size="5"
    >
      <QrCode.Frame role="img" aria-label="QR code for the event page">
        <QrCode.Pattern />
      </QrCode.Frame>
    </QrCode.Root>
    <figcaption>Scan to open the event page</figcaption>
  </figure>
</template>

Composition

Typical part hierarchy

QrCode.Root
├── QrCode.Frame <svg>
│   ├── Background <rect> (built in)
│   └── QrCode.Pattern <path>
├── QrCode.Overlay (optional)
├── QrCode.DownloadTrigger (optional)
└── QrCode.Context (optional)

Root owns generation state. Frame and Pattern render the SVG. Overlay and DownloadTrigger are optional. Context exposes the current value and helpers.

Kappa follows Ark UI QR Code for encoding, reactive values, context, and image downloads. Kappa defaults encoding.border to four modules in both Root anduseQrCode, rather than Ark's one-module default. This clear border is encoded into the SVG and survives resizing and downloads. Explicit encoding values are preserved; do not reduce the border below four modules for production codes.

Frame includes an SVG background so exported images are opaque. Pattern carries a foreground fill for export. Without page CSS, downloads use the white and dark fallback colors. With Frame as-child, include a background rectangle in your custom SVG. RootProvider uses the supplied machine unchanged; create it with Kappa's useQrCode to get the same border default.

Examples

Controlled

Bind the destination with v-model, or change it through Context.

Destination

<script setup lang="ts">
import { ref } from "vue";
import { Button } from "@dicehub/kappa/components/button";
import { Input } from "@dicehub/kappa/components/input";
import { Label } from "@dicehub/kappa/components/label";
import { QrCode } from "@dicehub/kappa/components/qr-code";

const link = ref("https://example.com/guide");
</script>

<template>
  <Label for="qr-code-link">Destination</Label>
  <Input id="qr-code-link" v-model="link" />

  <QrCode.Root id="controlled-link-code" v-model="link" :pixel-size="4">
    <QrCode.Frame role="img" aria-label="QR code for the current destination">
      <QrCode.Pattern />
    </QrCode.Frame>
    <QrCode.Context v-slot="context">
      <Button
        size="sm"
        variant="outline"
        @click="context.setValue('https://example.com/support')"
      >
        Use support link
      </Button>
    </QrCode.Context>
  </QrCode.Root>
</template>

Overlay

Use :encoding="{ ecc: 'H' }" for a small central mark. High error correction reduces the risk from covered modules; it does not guarantee that an arbitrary logo will scan. Keep the overlay small and test the final image.

<script setup lang="ts">
import { QrCode } from "@dicehub/kappa/components/qr-code";
</script>

<template>
  <QrCode.Root
    id="branded-link-code"
    default-value="https://example.com/account"
    :encoding="{ ecc: 'H' }"
    :pixel-size="6"
  >
    <QrCode.Frame role="img" aria-label="QR code for the account page">
      <QrCode.Pattern />
    </QrCode.Frame>
    <QrCode.Overlay aria-hidden="true">K</QrCode.Overlay>
  </QrCode.Root>
</template>

Download

Export the current code as PNG, JPEG, or WebP. The encoded clear border and SVG background remain in the downloaded image. Ark exports image or SVG overlays, not arbitrary HTML or text overlays. Test the downloaded file as well as the displayed code.

<script setup lang="ts">
import { QrCode } from "@dicehub/kappa/components/qr-code";
</script>

<template>
  <QrCode.Root
    id="downloadable-link-code"
    default-value="https://example.com/contact"
    :pixel-size="6"
  >
    <QrCode.Frame role="img" aria-label="QR code for the contact page">
      <QrCode.Pattern />
    </QrCode.Frame>
    <QrCode.DownloadTrigger file-name="contact-link.png" mime-type="image/png">
      Download PNG
    </QrCode.DownloadTrigger>
  </QrCode.Root>
</template>

Accessibility

Give Frame role="img" and an accessible label that describes the destination.
Show the destination as readable text when users must verify it before scanning.
Keep strong foreground and background contrast. Do not invert the pattern in dark mode.
Keep at least four clear modules on each side, including in exported images.
Keep overlays small and test generated codes with more than one scanner.

API Reference

QrCode.Root

Prop	Type	Default	Description
`modelValue`	`string`	`—`	Controlled value encoded by the QR code. Use v-model for two-way binding.
`defaultValue`	`string`	`""`	Initial value for uncontrolled use.
`pixelSize`	`number`	`10`	Pixel size of each generated QR module.
`encoding`	`QrCodeGenerateOptions`	`{ border: 4 }`	Generator options. Omitted border defaults to four clear modules; explicit values are preserved. Use ecc: 'H' for a small overlay.
`id / ids`	`string / object`	`generated`	Stable machine and element identifiers.
`asChild`	`boolean`	`false`	Merges root behavior and Kappa attributes onto one direct child.

QrCode.DownloadTrigger

Prop	Type	Default	Description
`fileName`	`string`	`—`	Required file name for the generated image.
`mimeType`	`"image/png" \| "image/jpeg" \| "image/webp"`	`—`	Required image format.
`quality`	`number`	`browser default`	Optional JPEG or WebP image quality.
`variant / size / icon`	`ButtonVisualProps`	`Button defaults`	Uses the shared Kappa Button visual contract.

Parts

Part	Element	Description
`QrCode.Root`	`div`	Owns the encoded value and generated matrix.
`QrCode.Frame`	`svg`	Provides the square SVG canvas.
`QrCode.Pattern`	`path`	Renders the generated QR modules.
`QrCode.Overlay`	`div`	Centers a small mark above the pattern.
`QrCode.DownloadTrigger`	`button`	Downloads the current code as an image.
`QrCode.Context`	`renderless`	Exposes value, setValue, and data URL helpers.
`QrCode.RootProvider`	`div`	Provides an external useQrCode state machine.

Events

Event	Payload	Description
`update:modelValue`	`string`	Emitted when context.setValue changes the encoded value.
`valueChange`	`QrCodeValueChangeDetails`	Reports each value change.

Exports

Export	Description
`QrCode`	Compound component and root alias.
`QrCodeRoot and named parts`	Unaugmented component exports.
`useQrCode / useQrCodeContext`	Ark UI QR code composables.
`QrCode props, events, API, and generator types`	Public TypeScript contracts.