A Vue.js wrapper component that turns everything into fun scratch cards

vue-scratchable

A Vue.js wrapper component that turns everything into fun scratch cards. Includes touch support without additional dependencies.

It can also calculate percentage value of the scratchables's cleared area.

? Installation

Install it with npm:

npm i vue-scratchable

Or directly in the browser:

<script src="https://unpkg.com/vue-scratchable@latest/dist/vue-scratchable.umd.min.js"></script>

✨ Usage

Register the component globally:

import VueScratchable from 'vue-scratchable';

Vue.component('vue-scratchable', VueScratchable);

Or use it locally in your Single File Components:

import VueScratchable from 'vue-scratchable';

export default {
  /* ... */
  components: {
    VueScratchable,
  },
  /* ... */
};

In both cases you are now able to use it in the <template> of a component:

<vue-scratchable>
  <h1>Hello Scratchable World</h1>
</vue-scratchable>

? Complete example as a Single File Component

This code is taken from this project's App.vue file to showcase the component's easy way of use.

<template>
  <div id="app">
    <h1>A beautiful parrot got trapped behind some paper.</h1>
    <h2>Scratch them free!</h2>
    <vue-scratchable
      v-slot="{ init }"
      :brushOptions="brush"
      :hideOptions="hide"
      getPercentageCleared
      @percentageUpdate="updatePoints"
    >
      <div class="wrapper">
        <img
          :src="require('./assets/mehmet-turgut-kirkgoz-vnayhPykN5Q-unsplash.jpg')"
          @load="init()"
        >
        <h3>{{ subline }}</h3>
      </div>
    </vue-scratchable>
    <p>You scratched {{ percentage }}% free.</p>
    <pre>Photo by <a href="https://unsplash.com/@tkirkgoz?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Mehmet Turgut Kirkgoz</a> on <a href="https://unsplash.com/t/animals?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></pre>
  </div>
</template>

<script>
import VueScratchable from 'vue-scratchable';
import paperPattern from './assets/natural-paper-texture.jpg';

export default {
  name: 'App',
  components: {
    VueScratchable,
  },
  computed: {
    subline() {
      return this.percentage < 100
        ? `? There is still ${100 - this.percentage}% left for me to be free... ?`
        : '? Thank you for scratching me free! ?';
    },
  },
  data() {
    return {
      percentage: 0,
      hide: {
        type: 'pattern',
        src: paperPattern,
        repeat: 'repeat',
      },
      brush: {
        size: 60,
        shape: 'round',
      },
    };
  },
  methods: {
    updatePoints(percentage) {
      this.percentage = percentage;
    },
  },
};
</script>

<style>
body {
  background-color: #333;
  margin: 0;
}

#app {
  font-family: 'Open Sans', sans-serif;
  color: white;
  display: flex;
  flex-direction: column;
  align-items: center;
  max-width: 1200px;
  margin: 0 auto;
  margin-top: 50px;
}

.vue-scratchable-wrapper {
  background-color: white;
}

h3 {
  color: #2c3e50;
  text-align: center;
}

a {
  color: #2196f3;
}
</style>

⚙️ Configuration

? Slot

? Props

?️ Brush options

? Hide options

There are two different types of fill that can be applied to the scratchable area: a solid colour or a canvas pattern. These are differentiated by the type property:

? Solid colour

Example:

const hide = {
  type: 'color',
  value: '#333',
};

?️‍? Pattern

Example:

const hide = {
  type: 'pattern',
  src: 'https://mdn.mozillademos.org/files/222/Canvas_createpattern.png',
  repeat: 'repeat',
};

? Events

✔️ Caveats

1. Img tags with local assets

When using img tags with local imported assets you have to call the init method of the component corresponding to the img tag's @load event. The init method can be accessed through the component's scoped slot.

Example:

<vue-scratchable v-slot="{ init }">
  <img
    :src="require('./img.jpg')"
    @load="init()"
  >
</vue-scratchable>

2. Using external images with patterns won't calculate percentage values.

Patterns from external sources can't be used together with the percentage calculation. If done anyways it will resolve in the following CORS error:

Error in v-on handler: "SecurityError: Failed to execute 'getImageData' on 'CanvasRenderingContext2D': The canvas has been tainted by cross-origin data."

3. Percentage calculation is very taxing on performance

The cleared area percentage calculation has to take every pixel of the canvas into consideration and analyzes whether they are cleared or not. Since this calculation gets called on every draw step this needs a lot of processing power. Because of that this feature is disabled by default and needs to be explicitly activated.

That's also why the percentageStride property should be set wisely and adjusted to your needs. It defines how many pixels should be skipped while calculating. This obviously also decreases the percentage's value accuracy.

GitHub