datamatrix-svg-ts

A TypeScript implementation of DataMatrix ECC 200 2D barcode generator that outputs SVG.

Background

This project is a TypeScript rewrite of the excellent datamatrix-svg library by Constantine (MIT License).

The original JavaScript implementation is compact and efficient, but we wanted a version that is native TypeScript with clear, documented code and full type safety. The code is refactored with descriptive names and comments explaining the DataMatrix encoding algorithms, making it easier to understand and maintain.

Additionally, this version supports all SVG-compatible color values (currentColor, rgb(), hsl(), named colors, etc.) instead of just hex colors.

Installation

npm install datamatrix-svg-ts

Quick Start

import { DATAMatrix } from 'datamatrix-svg-ts';

// Simple usage - just pass a string
const svg = DATAMatrix('Hello World!');
document.body.appendChild(svg);

Usage in React

import { useEffect, useRef } from 'react';
import { DATAMatrix } from 'datamatrix-svg-ts';

// Simple component
function DataMatrixCode({ message }: { message: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (containerRef.current) {
      containerRef.current.innerHTML = '';
      const svg = DATAMatrix(message);
      containerRef.current.appendChild(svg);
    }
  }, [message]);

  return <div ref={containerRef} />;
}

// With custom colors
function DataMatrixWithColors({ message }: { message: string }) {
  const containerRef = useRef<HTMLDivElement>(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 <div ref={containerRef} style={{ color: 'navy' }} />;
}

Error Handling

The library throws DataMatrixError for expected validation errors that can be caught and handled:

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;
  }
}

Error Codes

| Code | Description | |------|-------------| | EMPTY_MESSAGE | Message is empty (and allowEmptyMessage is false) | | MESSAGE_TOO_LONG | Encoded message exceeds DataMatrix maximum capacity |

Allowing Empty Messages

By default, empty messages throw an error. If you need to allow empty messages (produces a minimal DataMatrix), use the allowEmptyMessage option:

const svg = DATAMatrix({ message: '', allowEmptyMessage: true });

Two-Step API

For more control, you can separate encoding from rendering:

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

DATAMatrix(options | string): SVGSVGElement

Main function - generates a DataMatrix barcode as an SVG element.

Throws: DataMatrixError if message is empty or too long.

encodeToMatrix(message, rectangular?, allowEmptyMessage?): DataMatrixResult

Encodes a message into a pixel matrix (for custom rendering).

Throws: DataMatrixError if message is empty (unless allowEmptyMessage is true) or too long.

matrixToSvg(matrixResult, options?): SVGSVGElement

Converts a matrix to an SVG element.

DataMatrixError

Custom error class for validation errors. Has code property (DataMatrixErrorCode) and message.

Options

| 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 |

Palette Colors

Supports all SVG color values: #hex, rgb(), hsl(), named colors, currentColor, url(#gradient), etc.

License

MIT License

Based on datamatrix-svg by Constantine.