Demo

Install

yarn add scratch-reveal

Register

// registers <scratch-reveal>
import { registerScratchRevealElement } from 'scratch-reveal';
registerScratchRevealElement();

// Vue 3 plugin
import { createApp } from 'vue';
import { installScratchReveal } from 'scratch-reveal';
const app = createApp(App);
installScratchReveal(app);
app.mount('#app');

Usage (HTML)

<scratch-reveal
  width="300"
  height="300"
  complete-percent="60"
  show-status
  brush-size="15"
  brush-src="/demo/assets/brush.png"
  mask-src="/demo/assets/scratch-reveal.png"
  background-src="/demo/assets/scratch-reveal-background.svg"
></scratch-reveal>

Auto-size (follow parent/container size)

<div style="width: 420px; height: 240px;">
  <scratch-reveal
    style="width: 100%; height: 100%;"
    complete-percent="60"
    show-status
    brush-size="12"
    brush-src="/demo/assets/brush.png"
    mask-src="/demo/assets/scratch-reveal.png"
    background-src="/demo/assets/scratch-reveal-background.svg"
  ></scratch-reveal>
</div>

— If width/height attributes are omitted, the component will observe its own size and resize the canvas accordingly.

Events

const el = document.querySelector('scratch-reveal');
el.addEventListener('progress', (event) => {
  console.log(event.detail.percent);
});
el.addEventListener('complete', () => {
  console.log('done!');
});
el.addEventListener('error', (event) => {
  console.error(event.detail.message);
});

— progress (detail: { percent: number })
— complete (detail: { percent: 100 })
— error (detail: { message: string })

Note: events are dispatched with bubbles: true and composed: true, so they can be listened to outside of Shadow DOM (e.g. when <scratch-reveal> is used inside another Web Component).

Attributes

| Attribute | Type | Default | Description | |:------------------------:|:------------------:|:---------:|:--------------------------------------------------------------------------------------------------------------------------------| | width / height | number | 300 | Container/mask size in px. If omitted, size follows layout (auto-size). | | complete-percent | number | 60 | Percent cleared to consider done. | | brush-src | string | — | Brush image (required). | | brush-size | string \| number | 0 | Brush width: numbers mean percent of min(canvas width, height) (e.g., 12 = 12%). Use 80px for px. 0 = natural image size. | | mask-src | string | — | Top mask (scratched away) (required). | | background-src | string | — | Background beneath the mask (required). | | show-status | boolean | — | Optional: render status message for missing attrs / errors (good for dev). |

Styles

• Shadow styles via constructable stylesheet with <style> fallback for older browsers.
• Reuse the shipped CSS text:

  import { scratchRevealCssText } from 'scratch-reveal';
  // apply wherever you need

Vue 3.5+

• Register the custom element (see above).
• Optionally set isCustomElement in vite.config.ts for Volar/templates, or rely on the shipped src/vue.d.ts (global component scratch-reveal).

License

MIT