Vue E-Sign Canvas Signature Component

Common errors

• Error generating signature: Not Signned

  cause The `generate()` method was called on the `vue-esign` component when no drawing or signature was present on the canvas.
  fix Ensure the user has interacted with the canvas and drawn a signature before attempting to generate the image. Implement error handling for the `generate()` promise to alert the user or prevent generation if the canvas is empty.

• Generated JPEG image has a black background instead of transparent

  cause The JPEG image format (`image/jpeg`) does not support transparency. When a canvas is converted to JPEG, any transparent pixels are rendered as black.
  fix If transparency is required, use `image/png` or `image/webp` for the `format` option in the `generate()` method. Alternatively, if JPEG is mandatory, provide a specific `bgColor` prop to the `vue-esign` component to define a non-transparent background color for the canvas.

Warnings

• breaking The `bgColor` prop binding syntax changed for Vue 3 compatibility. In Vue 2, it used the `.sync` modifier (`:bgColor.sync`).
  Fix: For Vue 3, update the binding to use `v-model:bgColor` instead: `<vue-esign v-model:bgColor="bgColor" />`.
• gotcha When exporting to `image/jpeg` format, transparent areas of the canvas will be rendered as black, as JPEG does not support transparency.
  Fix: To preserve transparency, use `image/png` or `image/webp` formats. If `image/jpeg` is required, ensure a `bgColor` prop is explicitly set to prevent black backgrounds.
• gotcha The `generate()` method will reject its promise with an error (e.g., 'Not Signned') if called on an empty canvas where no signature has been drawn.
  Fix: Always wrap calls to `this.$refs.esign.generate()` in a `try...catch` block or handle the promise rejection using `.catch()` to gracefully manage cases where no signature exists.

Install

• npm install vue-esign npm
• yarn add vue-esign yarn
• pnpm add vue-esign pnpm

Imports

• VueEsign (default export)
  wrong:

  import { VueEsign } from 'vue-esign'

  correct:

  import VueEsign from 'vue-esign'

  The component is exported as a default export. Use this for both global plugin registration and local component usage.
• VueEsign (global plugin)
  wrong:

  const VueEsign = require('vue-esign'); Vue.use(VueEsign);

  correct:

  import VueEsign from 'vue-esign'; const app = createApp(App); app.use(VueEsign);

  For global registration in Vue 3 applications, import the default export and then use `app.use()`.
• VueEsign (local component)
  wrong:

  import { VueEsign } from 'vue-esign'; export default { components: { VueEsign } }

  correct:

  import VueEsign from 'vue-esign'; export default { components: { VueEsign } }

  When using vue-esign as a local component within a Vue SFC, import the default export and register it in the `components` option.

Quickstart

This quickstart demonstrates a basic Vue 3 component using vue-esign. It shows how to import the component, bind properties like line width, color, and background color, and use the `reset()` and `generate()` methods to clear the canvas or export the signature as a base64 image.

<!-- App.vue (or a component file) -->
<script setup lang="ts">
import { ref } from 'vue';
import VueEsign from 'vue-esign';

const esignRef = ref<InstanceType<typeof VueEsign> | null>(null);
const lineWidth = ref(6);
const lineColor = ref('#000000');
const bgColor = ref('');
const resultImg = ref('');
const isCrop = ref(false);
const isClearBgColor = ref(true);

const handleReset = () => {
  if (esignRef.value) {
    esignRef.value.reset();
    resultImg.value = ''; // Clear previous result on reset
  }
};

const handleGenerate = async () => {
  if (esignRef.value) {
    try {
      const res = await esignRef.value.generate({
        format: 'image/png',
        quality: 1
      });
      resultImg.value = res;
      console.log('Generated base64 image (truncated):', res.substring(0, 50) + '...');
    } catch (err: any) {
      alert(`Error generating signature: ${err.message || err}`);
    }
  }
};
</script>

<template>
  <div style="max-width: 800px; margin: 20px auto; border: 1px solid #eee; padding: 20px;">
    <h2>Vue E-Sign Demo</h2>
    <p>Sign below:</p>
    <vue-esign
      ref="esignRef"
      :width="800"
      :height="300"
      :isCrop="isCrop"
      :lineWidth="lineWidth"
      :lineColor="lineColor"
      v-model:bgColor="bgColor"
      :isClearBgColor="isClearBgColor"
      style="border: 1px dashed #ccc;"
    />
    <div style="margin-top: 20px;">
      <button @click="handleReset" style="margin-right: 10px; padding: 8px 15px;">Clear Signature</button>
      <button @click="handleGenerate" style="padding: 8px 15px; background-color: #4CAF50; color: white; border: none;">Generate Image</button>
    </div>
    <div v-if="resultImg" style="margin-top: 20px;">
      <h3>Generated Signature:</h3>
      <img :src="resultImg" alt="Generated Signature" style="max-width: 100%; border: 1px solid #ccc;"/>
      <p style="font-size: 0.8em; word-break: break-all;">Base64 output (truncated): {{ resultImg.substring(0, 100) }}...</p>
    </div>
    <div style="margin-top: 20px; border-top: 1px solid #eee; padding-top: 15px;">
      <h4>Configuration:</h4>
      <p>Line Width: <input type="number" v-model="lineWidth" /></p>
      <p>Line Color: <input type="color" v-model="lineColor" /></p>
      <p>Background Color: <input type="text" v-model="bgColor" placeholder="e.g., #f0f0f0, transparent" /></p>
      <p>Crop Signature: <input type="checkbox" v-model="isCrop" /></p>
      <p>Clear Background Color on Reset: <input type="checkbox" v-model="isClearBgColor" /></p>
    </div>
  </div>
</template>