ScratchCard

Neobrutalist-style scratch card component that uses HTML5 Canvas overlay on top of the content, drawing a mottled stripe layer. After the user erases a certain area with mouse/finger, the Canvas fades out and is destroyed, fully revealing the Vue content in the slot.

Demo

Preview

🎉 恭喜中奖！

自定义底色

大笔刷 (brushRadius=40)

大笔刷

渐隐时长 (fadeDuration=1000ms)

慢速渐隐

手动揭示 (revealAll)

一键揭示

Installation

pnpm dlx brutx-vue@latest add scratch-card

Usage

<script setup>
import { ScratchCard } from 'brutx-ui-vue'
</script>

<template>
    <ScratchCard class="w-full max-w-sm h-48">
        <div class="flex items-center justify-center h-full bg-brutal-accent">
            <p class="text-2xl font-black">🎉 Congratulations!</p>
        </div>
    </ScratchCard>
</template>

Custom Overlay

By default, a Neobrutalist two-color stripe pattern is drawn (--brutal-primary + --brutal-secondary). You can set a solid color overlay via the overlayColor prop:

<ScratchCard overlay-color="#FFE66D">
    <p>Content underneath</p>
</ScratchCard>

Programmatic Control

<script setup>
import { ref } from 'vue'
import { ScratchCard } from 'brutx-ui-vue'

const scratchCardRef = ref()
</script>

<template>
    <ScratchCard ref="scratchCardRef" />
    <button @click="scratchCardRef?.revealAll()">Reveal All</button>
</template>

API Reference

ScratchCard — Props

Name	Type	Default	Description
percentage	number | undefined	50	Automatically completes the reveal when this percentage of the covered area has been scratched; the default threshold is 50.
Details Declared type number | undefined Default value details Declaration DEFAULT_PERCENTAGE Source: packages/ui/src/components/scratch-card/ScratchCard.vue Resolved value 50 Source ScratchCard.vue:21 packages/ui/src/components/scratch-card/ScratchCard.vue
brushRadius	number | undefined	20	Sets the radius of the pointer scratch brush in pixels.
Details Declared type number | undefined Default value details Declaration DEFAULT_BRUSH_RADIUS Source: packages/ui/src/components/scratch-card/ScratchCard.vue Resolved value 20 Source ScratchCard.vue:22 packages/ui/src/components/scratch-card/ScratchCard.vue
overlayColor	string | undefined	undefined	Sets a solid background color for the Canvas overlay; when omitted, a two-color theme stripe pattern is used.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/scratch-card/ScratchCard.vue Resolved value undefined Source ScratchCard.vue:23 packages/ui/src/components/scratch-card/ScratchCard.vue
fadeDuration	number | undefined	300	The duration of the overlay fade-out after the completion threshold is reached, in milliseconds; reduced-motion preferences skip the animation.
Details Declared type number | undefined Default value details Declaration DEFAULT_FADE_DURATION Source: packages/ui/src/components/scratch-card/ScratchCard.vue Resolved value 300 Source ScratchCard.vue:24 packages/ui/src/components/scratch-card/ScratchCard.vue
class	string | undefined	undefined	CSS classes added to the scratch-card root container.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/scratch-card/ScratchCard.vue Resolved value undefined Source ScratchCard.vue:25 packages/ui/src/components/scratch-card/ScratchCard.vue

ScratchCard — Events

Name	Signature or type	Description
@progress	[percent: number]	Emits the current revealed-area percentage as scratching progresses; emissions are throttled.
Details Declared type [percent: number] Source ScratchCard.vue packages/ui/src/components/scratch-card/ScratchCard.vue
@completed	[]	Emitted when the overlay is removed after reaching the reveal threshold or calling revealAll.
Details Declared type [] Source ScratchCard.vue packages/ui/src/components/scratch-card/ScratchCard.vue

ScratchCard — Slots

Name	Signature or type	Description
#default	{}	The underlying scratch-card content covered by the Canvas overlay and revealed as it is scratched.
Details Declared type {} Source ScratchCard.vue packages/ui/src/components/scratch-card/ScratchCard.vue

ScratchCard — Exposes

Name	Signature or type	Description
isRevealed	boolean	The reveal state exposed on the component instance. Vue automatically unwraps its internal Ref, so read the boolean through scratchCardRef.value.isRevealed.
Details Declared type boolean Literal values false true Source ScratchCard.vue:108 packages/ui/src/components/scratch-card/ScratchCard.vue
revealAll	() => void	Immediately reveals all content and starts removing the overlay.
Details Declared type () => void Source ScratchCard.vue:109 packages/ui/src/components/scratch-card/ScratchCard.vue

Accessibility

• Keyboard control: The component sets tabindex="0"; pressing Enter or Space automatically reveals all content
• ARIA attributes: The component sets role="region", and aria-label defaults to the localized text scratchCard.ariaLabel (default: "Scratch Card")
• Motion reduction: When the user prefers prefers-reduced-motion: reduce, the fade-out animation is skipped and the Canvas is removed immediately
• Interaction hint: The Canvas overlay uses cursor-crosshair cursor to indicate interactivity