DataMatrix ECC 200 barcode generator as SVG - TypeScript implementation
npm install datamatrix-svg-tscurrentColor, rgb(), hsl(), named colors, etc.) instead of just hex colors.
bash
npm install datamatrix-svg-ts
`
Quick Start
`typescript
import { DATAMatrix } from 'datamatrix-svg-ts';
// Simple usage - just pass a string
const svg = DATAMatrix('Hello World!');
document.body.appendChild(svg);
`
Usage in React
`tsx
import { useEffect, useRef } from 'react';
import { DATAMatrix } from 'datamatrix-svg-ts';
// Simple component
function DataMatrixCode({ message }: { message: string }) {
const containerRef = useRef(null);
useEffect(() => {
if (containerRef.current) {
containerRef.current.innerHTML = '';
const svg = DATAMatrix(message);
containerRef.current.appendChild(svg);
}
}, [message]);
return ;
}
// With custom colors
function DataMatrixWithColors({ message }: { message: string }) {
const containerRef = useRef(null);
useEffect(() => {
if (containerRef.current) {
containerRef.current.innerHTML = '';
const svg = DATAMatrix({
message,
dimension: 200,
palette: {
foreground: 'currentColor', // Inherits CSS color
background: '#f0f0f0' as const
}
});
containerRef.current.appendChild(svg);
}
}, [message]);
return ;
}
`
Error Handling
The library throws DataMatrixError for expected validation errors that can be caught and handled:
`typescript
import { DATAMatrix, DataMatrixError } from 'datamatrix-svg-ts';
try {
const svg = DATAMatrix({ message: userInput });
} catch (e) {
if (e instanceof DataMatrixError) {
// Handle validation errors
switch (e.code) {
case 'EMPTY_MESSAGE':
console.log('Please enter a message');
break;
case 'MESSAGE_TOO_LONG':
console.log('Message exceeds DataMatrix capacity (~1556 bytes)');
break;
}
} else {
// Unexpected error (programming bug) - rethrow
throw e;
}
}
`
$3
| Code | Description |
|------|-------------|
| EMPTY_MESSAGE | Message is empty (and allowEmptyMessage is false) |
| MESSAGE_TOO_LONG | Encoded message exceeds DataMatrix maximum capacity |
$3
By default, empty messages throw an error. If you need to allow empty messages (produces a minimal DataMatrix), use the allowEmptyMessage option:
`typescript
const svg = DATAMatrix({ message: '', allowEmptyMessage: true });
`
Two-Step API
For more control, you can separate encoding from rendering:
`typescript
import { encodeToMatrix, matrixToSvg } from 'datamatrix-svg-ts';
// Step 1: Encode message to matrix
const matrixResult = encodeToMatrix('Hello World!');
// Step 2: Render matrix to SVG
const svg = matrixToSvg(matrixResult, {
dimension: 512,
palette: { foreground: '#000', background: '#fff' }
});
// Or use the matrix data for custom rendering (Canvas, PNG, etc.)
// matrixResult.matrix[y][x] === 1 means black module
`
API
$3
Main function - generates a DataMatrix barcode as an SVG element.
Throws: DataMatrixError if message is empty or too long.
$3
Encodes a message into a pixel matrix (for custom rendering).
Throws: DataMatrixError if message is empty (unless allowEmptyMessage is true) or too long.
$3
Converts a matrix to an SVG element.
$3
Custom error class for validation errors. Has code property (DataMatrixErrorCode) and message.
$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| message | string | '' | The message to encode |
| dimension | number | 256 | Output size in pixels |
| padding | number | 2 | Padding in modules |
| palette | Palette | { foreground: '#000' } | Colors |
| rectangular | boolean | false | Rectangular format |
| allowEmptyMessage | boolean | false | Allow empty message without error |
$3
Supports all SVG color values: #hex, rgb(), hsl(), named colors, currentColor, url(#gradient)`, etc.