QRCode
A QR code component based on a pure TypeScript, zero-dependency encoder (built in-house) that outputs inline SVG and is scannable and downloadable.
Basic Usage
Basic QR code
value accepts arbitrary text (numeric / alphanumeric / byte modes are chosen automatically); the default size is 128px.
Sizes
Custom size
size controls the rendered width/height (minimum 32; invalid values fall back to 128); the SVG scales via viewBox, so any size stays sharp.
Error Correction Level
error-correction levels compared
error-correction accepts four levels, l/m/q/h (default l), all genuinely implemented by the in-house encoder (versions 1–40) — no more silent normalization. Higher levels tolerate more damage (H ≈ 30%) at the cost of a denser symbol; use q/h when embedding a center logo or scanning in poor light.
Center Logo
icon center logo (with high error correction)
icon is the center image URL (rendered inline in the SVG, on an automatic background pad); icon-size defaults to size/5 (the usual ≤1/5 rule of thumb) — an oversized logo eats the correction budget and can make the code unscannable, so pair logos with q/h correction.
Colors and Dark-theme Scannability
color / bg-color customization
Foreground color defaults to the fixed dark #18181b (paired with the white quiet zone for dark-theme scannability; override via --oas-qrcode-color); it accepts any CSS color or one of 11 preset names (e.g. blue → var(--oas-preset-blue)). Background bg-color defaults to pure white — scannability outranks theme consistency, so the code stays scannable in dark themes (override globally via --oas-qrcode-bg if needed). The quiet-zone margin margin defaults to 4 modules (the QR standard requirement).
Shapes and Gradients
dot-shape module shape / corner-shape finder pattern
dot-shape: square (default) / rounded / dots; corner-shape: square (default) / rounded (rounds the three finder patterns). Invalid values silently fall back to square. Module shapes change rendering only — the module matrix and error-correction encoding stay identical.
gradient foreground (overrides color) + icon-hide-dots
gradient takes a JSON array (2–3 colors, e.g. '["#0b6cff","#7c3aed"]') and renders a linear gradient along gradient-angle (CSS convention: 0° bottom-to-top, 90° left-to-right); when set it overrides color, and invalid values fall back to color. icon-hide-dots clears the modules under the center logo (so the dot grid does not bleed through a semi-transparent logo). Scannability note: dots/rounded shapes and gradients reduce edge contrast — for low light, low-resolution printing or long content keep the default dot-shape="square", or raise error-correction to q/h.
Status (expired / loading / scanned)
status state machine (click refresh on expired)
Click "Refresh" on the expired code to fire the oas-refresh event (this demo simulates a refresh flow: loading → active).
status: active (default) / expired / loading / scanned. Any non-active value overlays the code: expired shows "QR code expired" plus a refresh button (click fires oas-refresh), loading shows a spinner (aria-busy), scanned shows "Scanned". The overlay content can be fully customized by cloning a template[slot="status"].
Download PNG
download() offscreen rasterize
download() rasterizes the current code offscreen into a PNG download — the render layer stays SVG-only (vector + SSR snapshot consistency), with no resident canvas; the center logo is drawn in a second pass during rasterization (browsers block external images inside SVG loaded via <img>).
Empty and Overflow
Empty value
When value is empty, a "No content" placeholder is shown; when the content exceeds the capacity of versions 1–40 at the chosen correction level (2953 bytes at v40-L), a "Content is too long" message is shown.
Accessibility
aria-label
The graphic element carries `role="img"`; the `aria-label` attribute takes precedence, otherwise it falls back to the locale default copy (Chinese "二维码" / English "QR code"), readable by screen readers.
API
oas-qrcode
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
aria-label | Accessible name of the container; defaults to i18n | — | — |
bg-color | Background color (default white — scanners need a light quiet zone; stays white in dark theme for scannability; override via --oas-qrcode-bg) | string | — |
color | Foreground (module) color, default fixed dark #18181b (paired with the white quiet zone for dark-theme scannability; override via --oas-qrcode-color, preset name, or any color value) | string | — |
corner-shape | Finder pattern shape: square (default, pixel-identical to the module grid) / rounded (rounds the three finder patterns) | string | square |
dot-shape | Module shape: square (default) / rounded / dots (invalid values silently fall back to square) | string | square |
error-correction | Error correction level l/m/q/h (all four implemented; default el. Use q/h for a center logo or weak-light/damaged scenarios) | string | l |
gradient | Gradient foreground: JSON array of 2–3 colors (e.g. ["#0b6cff","#7c3aed"]); when set it overrides color (invalid values fall back to color) | string | — |
gradient-angle | Gradient angle (CSS convention: 0° bottom-to-top, 90° left-to-right, default 45) | string | 45 |
icon | Center logo image URL (use with error-correction="h" to keep scannability) | string | — |
icon-hide-dots | Clears the modules under the center logo (boolean attribute, so the dot grid does not bleed through a semi-transparent logo) | boolean | — |
icon-size | Center logo size in px (default size/5, clamped to [16, size/2]) | — | — |
margin | Quiet-zone margin in modules (default 4) | string | 4 |
size | Rendered width/height (px) | string | 128 |
status | State machine: active (default) / expired (overlay, refresh button fires oas-refresh) / loading / scanned | string | active |
value | QR code content text | string | — |
Events
| Event | Description |
|---|---|
oas-refresh | Fired when the refresh button is clicked in expired state; the host reassigns content and switches back to active |
Slots
| Name | Description |
|---|---|
template[slot="status"] | Custom status overlay content (built-in overlays per state by default) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-qrcode-bg | #ffffff |
--oas-qrcode-color | #18181b |
The encoder functions (encodeQR / matrixToPath, etc.) are exported by @oas-ui/ui and can be used directly for SSR or custom rendering.