Scratch & reveal Web Component: mask + background with brush-only reveal, Vue-friendly, shadow-styled.
npm install scratch-revealscratch-reveal
Web Component for scratch-to-reveal: canvas mask, background under it, custom brush. Ready for plain browser usage and Vue 3.
console
yarn add scratch-reveal
`
Register
`ts
// registers
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)
`html
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"
>
`
$3
`html
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"
>
`
— If width/height attributes are omitted, the component will observe its own size and resize the canvas accordingly.
Events
`js
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 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