Barcode
Generate one-dimensional barcodes from ASCII text or product numbers. The component renders SVG and exports SVG, PNG, JPEG, or WebP.
Import
import { NsBarcode } from '@ns/ui'
import type { BarcodeExpose, BarcodeFormat, BarcodeStatus } from '@ns/ui'
Examples
Basic
<script setup lang="ts">
import { NsBarcode } from '@ns/ui'
</script>
<template>
<NsBarcode value="NS2026111800001" />
</template>
Formats
Code 128 accepts ASCII 0–127. Code 39 accepts uppercase letters, digits, and selected punctuation. The remaining formats accept digits only.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
const items = [
{ format: 'CODE128', value: 'Hello-NsUI' },
{ format: 'EAN13', value: '690123456789' },
{ format: 'EAN8', value: '9638507' },
{ format: 'UPC', value: '03600029145' },
{ format: 'CODE39', value: 'NSUI-2026' },
{ format: 'ITF14', value: '1540014128876' },
{ format: 'ITF', value: '123456' }
] as const
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace v-for="item in items" :key="item.format" direction="vertical">
<span>{{ item.format }}</span>
<NsBarcode :format="item.format" :value="item.value" />
</NsSpace>
</NsSpace>
</template>
Product Numbers
EAN-13 accepts 12 or 13 digits; EAN-8 accepts 7 or 8; UPC-A accepts 11 or 12; ITF-14 accepts 13 or 14. A missing GS1 check digit is added automatically. A complete number is validated. EAN and UPC display grouped digits with extended guard bars.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical"
><span>Check digit added</span><NsBarcode value="690123456789" format="EAN13"
/></NsSpace>
<NsSpace direction="vertical"
><span>Complete number validated</span><NsBarcode value="6901234567892" format="EAN13"
/></NsSpace>
<NsSpace direction="vertical"
><span>Incorrect check digit</span><NsBarcode value="6901234567891" format="EAN13"
/></NsSpace>
</NsSpace>
</template>
Bar Width and Height
bar-width specifies the narrowest module width. Total width depends on the content and format. height excludes text and padding.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="end">
<NsSpace v-for="width in [1, 2, 3]" :key="width" direction="vertical">
<span>bar-width={{ width }}</span
><NsBarcode value="NS2026" :bar-width="width" />
</NsSpace>
</NsSpace>
<NsSpace wrap align="end">
<NsSpace v-for="height in [40, 60, 80]" :key="height" direction="vertical">
<span>height={{ height }}</span
><NsBarcode value="NS2026" :height="height" />
</NsSpace>
</NsSpace>
</NsSpace>
</template>
Text
text changes the caption without changing the encoded content. Custom text disables product digit groups and extended guard bars. Empty text or display-value="false" removes the text area.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="start">
<NsSpace direction="vertical"
><span>display-value=true</span><NsBarcode value="NS2026"
/></NsSpace>
<NsSpace direction="vertical"
><span>display-value=false</span><NsBarcode value="NS2026" :display-value="false"
/></NsSpace>
<NsSpace direction="vertical"
><span>Custom text</span><NsBarcode value="NS2026" text="Order NS2026"
/></NsSpace>
<NsSpace direction="vertical"
><span>Empty text</span><NsBarcode value="NS2026" text=""
/></NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace v-for="size in [12, 14, 18]" :key="size" direction="vertical">
<span>font-size={{ size }}</span
><NsBarcode value="NS2026" :font-size="size" />
</NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace v-for="margin in [2, 8]" :key="margin" direction="vertical">
<span>text-margin={{ margin }}</span
><NsBarcode value="NS2026" :text-margin="margin" />
</NsSpace>
<NsSpace direction="vertical"
><span>font-family=serif</span><NsBarcode value="NS2026" font-family="serif"
/></NsSpace>
</NsSpace>
</NsSpace>
</template>
Colors
Bars and text share color. The default remains black on white in dark mode. Use transparent backgrounds only over a light surface.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical"><span>Default</span><NsBarcode value="NS2026" /></NsSpace>
<NsSpace direction="vertical"
><span>Custom</span><NsBarcode value="NS2026" color="#14532d" background-color="#f0fdf4"
/></NsSpace>
<NsSpace direction="vertical"
><span>Transparent</span><NsBarcode value="NS2026" background-color="transparent"
/></NsSpace>
</NsSpace>
</template>
Padding and Quiet Zones
Horizontal padding is at least the greater of padding and the required quiet zone. Outside product digits retain their space even when quiet zones are disabled. Keep sufficient quiet zones for scanning.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="start">
<NsSpace v-for="padding in [0, 10, 20]" :key="padding" direction="vertical">
<span>padding={{ padding }}</span
><NsBarcode value="NS2026" :padding="padding" bordered />
</NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace direction="vertical"
><span>quiet-zone=true</span><NsBarcode value="NS2026" :padding="0" bordered
/></NsSpace>
<NsSpace direction="vertical"
><span>quiet-zone=false</span
><NsBarcode value="NS2026" :padding="0" :quiet-zone="false" bordered
/></NsSpace>
</NsSpace>
</NsSpace>
</template>
Border
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsSpace direction="vertical"><span>bordered=false</span><NsBarcode value="NS2026" /></NsSpace>
<NsSpace direction="vertical"
><span>bordered=true</span><NsBarcode value="NS2026" bordered
/></NsSpace>
</NsSpace>
</template>
Code 39 Checksum
The optional modulo-43 check character changes the bars only. The caption remains the original value. Other formats ignore checksum.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsSpace direction="vertical"
><span>checksum=false</span><NsBarcode value="NSUI-2026" format="CODE39"
/></NsSpace>
<NsSpace direction="vertical"
><span>checksum=true</span><NsBarcode value="NSUI-2026" format="CODE39" checksum
/></NsSpace>
</NsSpace>
</template>
Status and Refresh
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsMessage, NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
import type { BarcodeStatus } from '@ns/ui'
const status = ref<BarcodeStatus>('expired')
const refresh = () => {
status.value = 'active'
NsMessage.success('Refresh requested')
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsRadioGroup v-model="status" type="button">
<NsRadio value="active">active</NsRadio>
<NsRadio value="loading">loading</NsRadio>
<NsRadio value="expired">expired</NsRadio>
</NsRadioGroup>
<NsBarcode value="NS2026" :status="status" @refresh="refresh" />
<NsBarcode
value="NS2026"
status="expired"
expired-text="Order expired"
refresh-text="Regenerate"
@refresh="refresh"
/>
</NsSpace>
</template>
Custom Status Slot
<script setup lang="ts">
import { NsBarcode, NsButton, NsMessage, NsSpace } from '@ns/ui'
const refresh = () => NsMessage.info('Barcode requested')
</script>
<template>
<NsBarcode value="NS2026" status="expired" @refresh="refresh">
<template #status="{ status, refresh: requestRefresh }">
<NsSpace direction="vertical" align="center">
<span>{{ status === 'expired' ? 'Order barcode expired' : 'Fetching barcode' }}</span>
<NsButton icon="refresh" size="small" @click="requestRefresh">Fetch again</NsButton>
</NsSpace>
</template>
</NsBarcode>
</template>
Validation
Empty content reserves a fixed 100-module placeholder without an error. Invalid content displays a format message and logs the specific reason in development. Override the message with invalid-text.
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsInput, NsSelect, NsSpace } from '@ns/ui'
import type { BarcodeFormat } from '@ns/ui'
const value = ref('690123456789')
const format = ref<BarcodeFormat>('EAN13')
const options = ['CODE128', 'EAN13', 'EAN8', 'UPC', 'CODE39', 'ITF14', 'ITF'].map((value) => ({
label: value,
value
}))
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsSelect
v-model="format"
:options="options"
aria-label="Barcode format"
style="width: 160px"
/>
<NsInput v-model="value" aria-label="Barcode content" style="width: 240px" />
</NsSpace>
<NsBarcode :value="value" :format="format" />
<NsBarcode value="abc" format="EAN13" invalid-text="Enter a valid product number" />
</NsSpace>
</template>
Download and SVG Source
Exports include the background, padding, and text, excluding borders and status overlays. Bitmap exports wait for page fonts and retain the content and style captured when called.
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsButton, NsMessage, NsSpace, NsTextarea } from '@ns/ui'
import type { BarcodeExpose } from '@ns/ui'
const barcode = ref<BarcodeExpose | null>(null)
const source = ref('')
const download = async (type: 'image/png' | 'image/svg+xml') => {
try {
const url = await barcode.value?.toDataURL(type, { scale: 3 })
if (!url) return
const link = document.createElement('a')
link.href = url
link.download = type === 'image/png' ? 'barcode.png' : 'barcode.svg'
link.click()
NsMessage.success('Barcode exported')
} catch {
NsMessage.error('Export failed; check the barcode content')
}
}
const showSource = () => {
source.value = barcode.value?.toSvgString() ?? ''
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsBarcode ref="barcode" value="690123456789" format="EAN13" />
<NsSpace wrap>
<NsButton icon="download" @click="download('image/png')">Download PNG</NsButton>
<NsButton icon="download" @click="download('image/svg+xml')">Download SVG</NsButton>
<NsButton @click="showSource">Show SVG source</NsButton>
</NsSpace>
<NsTextarea v-model="source" readonly :rows="4" aria-label="SVG source" />
</NsSpace>
</template>
Accessible Names
The default accessible name reads the complete number, including an automatically added check digit. aria-label takes precedence over alt, including an explicit empty string.
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsBarcode value="NS2026" alt="Order NS2026" />
<NsBarcode value="NS2026" alt="Order number" aria-label="Dispatch NS2026" />
</NsSpace>
</template>
Props
| Prop | Description | Type | Default |
|---|---|---|---|
| value | Content; empty content shows a placeholder | string | '' |
| format | Encoding format | BarcodeFormat | 'CODE128' |
| barWidth | Narrowest module width in px; positive | number | 2 |
| height | Bar height in px, excluding text and padding; positive | number | 60 |
| padding | Padding in px; horizontal space also accommodates quiet zones and outside digits | number | 10 |
| quietZone | Preserve the minimum format-specific quiet zones | boolean | true |
| color | Bar and text color | string | '#000' |
| backgroundColor | Background including padding | string | '#FFF' |
| displayValue | Show text | boolean | true |
| text | Custom caption; disables product digit grouping | string | undefined |
| fontSize | Font size in px; positive | number | 14 |
| fontFamily | Font used for display and export | string | 'monospace' |
| textMargin | Gap between bars and text in px | number | 4 |
| checksum | Append a modulo-43 check character for Code 39 | boolean | false |
| bordered | Show border | boolean | false |
| status | Current status | BarcodeStatus | 'active' |
| expiredText | Expiration message, including an empty string | string | Locale value |
| refreshText | Refresh button text, including an empty string | string | Locale value |
| invalidText | Invalid-content message, including an empty string | string | Locale value with format name |
| alt | Accessible alternative; otherwise the complete number | string | undefined |
| ariaLabel / aria-label | Accessible name; overrides alt | string | undefined |
Events
| Event | Description | Arguments |
|---|---|---|
| refresh | Expired refresh button clicked or status-slot refresh called | None |
Slots
| Slot | Description | Scope |
|---|---|---|
| status | Custom loading / expired overlay | { status: 'loading' | 'expired', refresh: () => void } |
Methods
Access methods through a template ref typed as BarcodeExpose.
| Method | Description | Signature |
|---|---|---|
| toSvgString | SVG source; empty or invalid content returns '' | () => string |
| toDataURL | Export image; empty or invalid content rejects; invalid-content errors are named BarcodeValueError | (type?: BarcodeExportType, options?: BarcodeExportOptions) => Promise<string> |
Types
type BarcodeFormat = 'CODE128' | 'EAN13' | 'EAN8' | 'UPC' | 'CODE39' | 'ITF14' | 'ITF'
type BarcodeStatus = 'active' | 'loading' | 'expired'
type BarcodeExportType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml'
interface BarcodeExportOptions {
scale?: number
quality?: number
}
interface BarcodeExpose {
toDataURL: (type?: BarcodeExportType, options?: BarcodeExportOptions) => Promise<string>
toSvgString: () => string
}
BarcodeProps and BarcodeEmits are also exported. Bitmap scale defaults to 2; SVG ignores scale. JPEG / WebP quality ranges from 0 to 1.
Notes
- Use dark bars on a light background, preferably with
bar-widthat least 1. Disable quiet zones only when sufficient outer whitespace already exists. SVG scales down in narrow containers; ensure displayed bars remain wide enough. - Default barcode colors stay black and white in dark mode. Borders and overlays follow the theme.
- Non-ASCII input, including Chinese text, cannot be encoded; use QR codes for such content. FNC characters are not supported as ordinary Code 128 input.
- EAN, UPC, and ITF-14 add or validate check digits automatically. ITF requires an even number of digits and adds no check digit.
- Code 39 requires uppercase letters. Apply
toUpperCase()as needed. Supported punctuation is- . space $ / + %;*is not accepted. - Long custom text may be clipped by the SVG boundary. Reduce
font-sizeor increasepadding; text width is not measured automatically. - A transparent JPEG background becomes black. Set an explicit light background for JPEG export.
- For printing, prefer
toSvgString()or direct page printing over enlarged bitmaps. Validate scanning and printing with the target devices. - Invalid or non-finite
barWidth,height, andfontSizefall back to defaults. InvalidpaddingandtextMarginbecome 0. Development warnings explain these fallbacks.