embroidery-qc-image

React component for rendering embroidery qc image. This package allows you to display custom embroidered designs on product mockups with configurable text, icons, colors, and fonts.

Installation

npm install embroidery-qc-image

Usage

import React from "react";
import { EmbroideryQCImage } from "embroidery-qc-image";
import type { EmbroideryQCConfig } from "embroidery-qc-image";

const exampleConfig: EmbroideryQCConfig = {
  image_url:
    "https://i.etsystatic.com/34592503/r/il/5d3e59/7253371633/il_fullxfull.7253371633_kgqr.jpg",
  sides: [
    {
      print_side: "Chest",
      positions: [
        {
          type: "TEXT",
          text: "Brian",
          text_shape: "No Curved",
          color: null,
          font: "Brittany Signature",
          floral_pattern: null,
          character_colors: ["Pink (1148)", "Lavender (1032)"],
        },
        {
          type: "TEXT",
          text: "EST. 2009",
          text_shape: "No Curved",
          color: "Light Denim (1133)",
          font: "Arial",
          character_colors: null,
          floral_pattern: "P61",
        },
        {
          type: "ICON",
          icon: 1,
          layer_colors: ["White (9)", "Red (1037)"],
        },
      ],
    },
    {
      print_side: "Sleeve",
      positions: [
        {
          type: "TEXT",
          text: "Ayanna",
          text_shape: "No Curved",
          color: "Terra Cotta (1477)",
          font: "Blackmate",
          character_colors: null,
        },
        {
          type: "TEXT",
          text: "Ryan",
          text_shape: "No Curved",
          color: "Terra Cotta (1477)",
          font: "Millie",
          character_colors: null,
        },
      ],
    },
  ],
};

const App: React.FC = () => {
  return (
    <div style={{ padding: "20px", maxWidth: "800px", margin: "0 auto" }}>
      <EmbroideryQCImage config={exampleConfig} />
    </div>
  );
};

export default App;

Export as Data URL

If you want to render the embroidery image yourself (for example with an <img> tag, download button, or upload flow), use the helper generateEmbroideryQCImageData. It returns a Data URL corresponding to the canvas output.

import { generateEmbroideryQCImageData } from "embroidery-qc-image";

const dataUrl = await generateEmbroideryQCImageData(exampleConfig, {
  width: 4200,        // optional, defaults to 4200
  height: 4800,       // optional, defaults to 4800
  mimeType: "image/png", // optional
  quality: 0.92,         // optional (used for jpeg/webp)
  lang: "vi"             // optional, "vi" | "en" (see Language below)
});

if (dataUrl) {
  // Display in an <img> tag
  <img src={dataUrl} alt="Embroidery preview" />;
  
  // Or trigger download
  const link = document.createElement("a");
  link.href = dataUrl;
  link.download = "embroidery.png";
  link.click();
}

Need a Blob instead? Use generateEmbroideryQCImageBlob with the same options.

Props

EmbroideryQCImage

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | EmbroideryQCConfig | Yes | Configuration object containing embroidery details | | className | string | No | Additional CSS classes | | style | React.CSSProperties | No | Inline styles | | lang | "vi" \| "en" | No | Language for rendered labels (see Language) |

Language

Labels are rendered in the resolved language, chosen in this priority order:

1. lang param — passed per render (the lang prop on <EmbroideryQCImage> or the lang option on the generate helpers).
2. IP / auto-detect — falls back to the browser locale (navigator.language). For IP-based detection, the consuming project should detect the region itself and pass the result through the lang param.
3. Default — "en".

import { EmbroideryQCImage } from "embroidery-qc-image";

// e.g. lang derived in your app from IP geolocation, user setting, etc.
<EmbroideryQCImage config={exampleConfig} lang="vi" />;

You can also set a global default once (lower priority than the lang param) via setLabelsLang:

import { setLabelsLang } from "embroidery-qc-image";

setLabelsLang("vi");

Configuration Structure

EmbroideryQCConfig

export interface TextPosition {
  type: 'TEXT';
  text: string;
  text_shape?: string | null;
  color?: string | null;
  font?: string | null;
  is_font_default?: boolean | null;
  character_colors?: string[] | null;
  floral_pattern?: string | null;
}

export interface IconPosition {
  type: 'ICON';
  icon: number;
  color?: string | null;
  layer_colors: string[];
}

export type Position = TextPosition | IconPosition;

export interface Side {
  print_side: string;
  positions: Position[];
}

export interface EmbroideryQCConfig {
  image_url?: string;
  error_message?: string | null;
  warning_message?: string | null;
  sides: Side[];
}

export type Lang = "vi" | "en";

export interface EmbroideryQCImageProps {
  config: EmbroideryQCConfig;
  className?: string;
  style?: React.CSSProperties;
  lang?: Lang;
}

License

MIT

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Support

For issues and questions, please open an issue on GitHub.