Barcode
A 1D barcode component based on a pure TypeScript, zero-dependency encoder (built in-house). The first release covers 6 symbologies (CODE128 / EAN-13 / EAN-8 / UPC-A / CODE39 / ITF-14), outputs inline SVG, and is scannable and downloadable.
Basic Usage
Basic barcode
value accepts arbitrary text (CODE128 auto switches between A/B/C subsets); the overall width is determined by the content (digits × symbology × bar-width + quiet zone) — the component has no size/width attribute, which is the biggest API difference from the QR code component.
Symbologies
6 symbologies in the first release
format: code128 (default, auto A/B/C) / ean13 / ean8 / upca / code39 / itf14; invalid values fall back to code128. For EAN/UPC, 12/7/11/13 data digits get the **check digit calculated automatically**; a full-length code is validated against its last digit. The EAN-13 first digit and the UPC-A first/last digits are rendered outside the guard bars per the standard, and guard bars extend downward. CODE39 upper-cases input automatically; ITF-14 is a fixed 13+1 digit carton code.
Bar Width & Height
bar-width / height
bar-width is the first parameter of scannability (X-dimension, default 2, floor 1); height controls the bar height only (default 100, excluding the text zone). Shortening the bar height lowers the first-read rate of laser scanners — keep the default for printed labels.
Human Readable Interpretation (HRI)
display-value / text-position / font size & spacing
display-value shows the HRI text by default (set display-value="false" to hide it); text-position is bottom (default) / top; font-size (default 16) and text-margin (default 4) control the text zone geometry. Text uses a generic sans — the barcode standard font OCR-B has no free license and is not embedded; hosts may load it via @font-face and override through ::part(text).
Colors & Dark-theme Scannability
color / bg-color customization
The bar color color defaults to fixed dark #18181b and accepts any CSS color or one of the 11 preset names; the quiet zone bg-color defaults to fixed white — scannability takes precedence over theme consistency, so it stays scannable under the dark theme (also overridable globally via the --oas-barcode-bg variable). Contrast warning: infrared scanners cannot read red-ish bars (red = white); keep "dark bars on a light background" when customizing colors.
Quiet Zone (hard scannability constraint)
margin quiet zone
margin is the left/right quiet zone (px, defaults to 10 × bar-width—the default output is scannable out of the box). Scanners require enough whitespace on both sides or they refuse to read — the component has a built-in guardrail: explicit values below 10 × bar-width are clamped up to the floor with a one-time console.warn. Hosts may enlarge it, not break it. The guardrail only enforces the floor — whether the quiet zone meets the physical requirements of a specific deployment (print size, scan distance, scanner model) is for the host to evaluate.
Invalid Input Feedback
oas-invalid event (error placeholder + event takeover)
Change the value to something invalid (letters, wrong digit count, wrong check digit) and click "Generate barcode" — the component renders an error placeholder and fires oas-invalid.
Invalid input comes in three classes, mapped one-to-one onto detail.reason of the oas-invalid event: charset (characters not allowed, e.g. letters in an EAN), length (wrong digit count), checksum (check digit mismatch). Hosts may take over the messaging (as this demo does); the component always renders its error placeholder as a fallback.
Download PNG
download() offscreen rasterize
download() rasterizes the current barcode offscreen into a PNG and triggers the download — the rendering layer stays SVG-only (vector + SSR snapshot consistency) with no persistent canvas; empty or invalid values return silently instead of producing an unscannable image.
Empty State
Empty value
When value is empty, a "No content" placeholder is shown.
Accessibility
aria-label
The graphic element carries `role="img"`; the `aria-label` attribute takes precedence, falling back to the locale default (Chinese "条码" / English "Barcode"), readable by screen readers. The component has no keyboard interaction (purely presentational, not in the tab order).
API
oas-barcode
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
aria-label | Accessible name of the graphic element (svg, role="img"); defaults to i18n | — | — |
bar-width | Bar width X-dimension (px, default 2, clamped to ≥1) | string | 2 |
bg-color | Quiet-zone background (default white — scanners need a light quiet zone; stays white in dark theme for scannability; override via --oas-barcode-bg) | string | — |
color | Bar color (default fixed dark #18181b — paired with the white background for dark-theme scannability; override via --oas-barcode-color, preset name, or any color value) | string | — |
display-value | Show the human readable interpretation (shown by default; set to "false" to hide) | string | — |
font-size | HRI text font size (px, default 16) | string | 16 |
format | Symbology: code128 (default, auto A/B/C subset switching) / ean13 / ean8 / upca / code39 / itf14 (invalid values fall back to code128) | string | code128 |
height | Bar height (px, default 100, excluding the text zone and guard-bar extension) | string | 100 |
margin | Left/right quiet zone (px, defaults to 10 × bar-width—scannable out of the box); explicit values below 10 × bar-width are clamped up to the floor with a one-time console.warn (scannability guardrail) | — | — |
text-margin | Spacing between text and bars (px, default 4) | string | 4 |
text-position | HRI text position: bottom (default) / top | string | bottom |
value | Barcode content (empty value shows the empty placeholder) | string | — |
Events
| Event | Description |
|---|---|
oas-invalid | Fired when invalid input renders the error placeholder, detail { reason }: charset (characters not allowed) / length (wrong digit count) / checksum (check digit mismatch); fires once per invalid input |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-barcode-bg | #ffffff |
--oas-barcode-color | #18181b |