Skip to main content

QRCode

Every example on this page is live, drawn by the library's Storybook, where you can also change its props and see the result.

Generates a QR code image from a text string. Useful for encoding URLs, identifiers, or other data that can be scanned by a mobile device.

The code is always square. Size it in CSS (size="40%", or size="fill" for the room its flex parent leaves) rather than in pixels worked out from your layout, so it shrinks with its box in a saved render. Beside or before the code, the caption is what gives way when a row runs short; give it a width of its own, by passing a node that has one, when the row also holds other flexible text.

Import​

import { QRCode } from "~lib/qr-code";

Props​

NameTypeRequiredDefaultDescription
textstringYesN/AThe text or URL to encode
sizenumber | string | "fill"No256The code's width in pixels, any CSS width such as "40%", or "fill"; always square
captionReactNodeNoN/AText shown with the code, such as "Scan to read", or a node drawn in its place
captionPlacement"below" | "beside" | "before"No"below"Whether the caption sits under the code, to its right or its left
captionSize"xs" | "sm" | "base" | "lg" | "xl"No"sm"Size of the caption text, on the same scale as Paragraph
captionLinesnumberNo1 below, no limit otherwiseThe most lines a string caption wraps to before it ends in "…"

Examples​

Default Size​

A QR code at the default 256x256px size:

Open Default in Storybook

Small​

A compact 100x100px QR code:

Open Small in Storybook

With a Caption​

Add a caption to tell people what the code is for. It sits centered under the code on one line, so the code and its caption always take the same height. A caption wider than the code stays on one line and the code stays centered above it:

Open With Caption in Storybook

Under a small code, set captionSize="xs" to keep the caption close to the code's width:

Open Thumbnail With Caption in Storybook

Set captionPlacement="beside" to put it to the right of the code instead, centered on its height:

Open Caption Beside in Storybook

Set captionPlacement="before" to put it to the left of the code, aligned against it. Use it when the code sits at the right-hand end of a row, where a caption after it would run off the edge. Like a caption beside the code, it wraps to the room the row leaves it:

Open Caption Before in Storybook

Sized to Its Box​

A pixel size stays that many pixels. A saved render of your widget is laid out again in boxes a little smaller than the one it was drawn in, so a code whose size you worked out from the layout keeps its pixels and runs past the edge. Give it a CSS width instead, such as size="40%" or size="100%": the code stays square, and shrinks with its box. With a caption, the code is that share of the block, which spans its parent:

Open Css Size in Storybook

size="fill" lets the code take the room its flex parent leaves. Down a column it grows to the column's width and is the first thing to give way when the column runs short, so a title above it and a caption under it always fit; across a row it takes the row's height, which the row needs of its own. The code is the shorter side of that room either way, centered:

Open Fill in Storybook
<div className="flex min-h-0 flex-1 flex-col gap-2">
  <Heading level={4}>Cinema listings</Heading>
  <QRCode text={listingsUrl} size="fill" caption="Scan to read" />
</div>

Larger and Longer Captions​

captionSize takes every size Paragraph does, so a caption beside a large code can be set as large as the text around it. Under the code a caption stays on one line unless you set captionLines; beside or before the code it wraps into the room the row leaves it, as far as captionLines when you set it. Either way it ends in "…" when it has more to say than its lines hold:

Open Caption Large in Storybook
Open Caption Lines in Storybook

A Caption That Is a Node​

Pass any node as the caption to set it yourself, such as text with a bold word or a Paragraph with a Badge. It is drawn in the caption's place, at captionSize unless it sets a size of its own. captionLines only limits a string, so give a node's own text its lines.

Sharing a Row With Other Text​

Beside or before the code, the caption is the part of the block that gives way: the code keeps its size, and the caption wraps as the row runs short. In a row with other flexible text, such as an address, the two texts share the room left over the way any two flexible items do, so one of them needs a set width or they squeeze each other. Give the caption a width of its own by passing a node with one: the block is then exactly the code, the gap between them (gap-2) and that width, which you can budget for in your layout.

Open Caption Node in Storybook
<div className="flex items-center gap-4">
  <Paragraph size="sm" truncate>
    {event.address}
  </Paragraph>
  <QRCode
    text={event.ticketsUrl}
    size={64}
    captionPlacement="before"
    caption={<div className="w-22">Scan for tickets</div>}
  />
</div>

See Also​