Scratch Card

A Scratch Card is an interactive reveal widget that allows users to “scratch” an overlay layer to uncover hidden content beneath it. It is commonly used for gamification flows such as rewards, coupon reveals, mystery unlocks, onboarding surprises, or engagement campaigns.

The widget renders two layers:

• Overlay → The top layer that users scratch away

• Base (Child) → The hidden content revealed underneath

When a configurable reveal threshold is reached, the widget can automatically complete and trigger an action.

Watch this on Youtube: https://www.youtube.com/watch?v=FYp5lN5-gWU

---

How It Works

The Scratch Card uses a brush-based interaction system. As the user drags (or taps, if enabled), portions of the overlay are cleared based on brush configuration (size, shape, opacity).

Internally, a controller tracks:

• Scratch progress (percentage revealed)

• Completion state

• Interaction state

Scratch Card widget showing an unscratched state and a fully revealed reward state.

When the scratched area reaches the configured percentage threshold, the widget triggers the onScratchComplete action.

---

Child Structure

The Scratch Card requires two child groups:

• overlay (Required) → The scratchable top layer

• base (Required) → The content revealed after scratching

If either is missing, the widget renders empty.

Both overlay and base child groups are mandatory. If one is not provided, the widget will not render.

---

Basic Usage Concept

ScratchCard
 ├── overlay (Image / Container / Design)
 └── base (Reward content / Coupon / Message)

---

Properties

Layout Properties

• height Defines the height of the scratch card.

• width Defines the width of the scratch card.

---

Scratch Appearence Properties

Property	Type	Default	Description
brushSize	double	20.0	Controls the size of the scratch brush. Larger values remove more overlay per interaction.
brushShape	string	circle	Defines the brush shape. Supported values: circle, square, star, heart, diamond.
brushColor	color	transparent	Color applied to the brush stroke.
brushOpacity	double	1.0	Opacity of the brush stroke.

---

Reveal & Completion Properties

Property	Type	Default	Description
revealFullAtPercent	number	75	Percentage threshold (0–100) at which the card automatically reveals fully. Example: 75 means the card completes when 75% is scratched.
gridResolution	integer	100	Controls scratch detection resolution. Higher values increase accuracy but may impact performance.
enableProgressAnimation	boolean	false	Enables animation while progressing toward full reveal.
isScratchingEnabled	boolean	true	Enables or disables scratching interaction.
enableTapToScratch	boolean	false	Allows scratching via tap gestures instead of drag gestures.
enableHapticFeedback	boolean	false	Enables haptic feedback during scratching interaction.

Warning: Setting isScratchingEnabled to false will completely disable interaction, even if other scratch properties are configured.

Tip For most use cases, keep gridResolution between 80–120. Extremely high values may impact performance on low-end devices.

---

Reveal Animation Properties

• revealAnimationType Animation triggered when fully revealed. Supported values:

  • none

  • fade

  • scale

  • slideup

  • slidedown

  • slideleft

  • slideright

  • bounce

  • zoomout

• animationDurationMs Duration of reveal animation in milliseconds.

Tip Avoid combining long animation durations with high grid resolution for large scratch surfaces, as it may increase frame workload.

---

Actions

onScratchComplete

Triggered once when the scratch progress reaches the configured threshold and the card is fully revealed.

This can be used to:

• Trigger navigation

• Unlock a reward

• Fire analytics events

• Update backend state

• Show a success modal

Trigger Type: onScratchComplete

Tip onScratchComplete fires only once per widget lifecycle. If you need repeatable behavior, the widget must be rebuilt.

---

Behavior Notes

• The base content remains hidden until scratching begins.

• The widget tracks progress internally using a controller.

• Completion fires only once per lifecycle.

• Performance depends on gridResolution and brush size.

• If scratching is disabled, the overlay remains static.

---

Common Use Cases

• Coupon reveal campaigns

• Reward unlock mechanics

• Gamified onboarding

• Festival promotions

• E-commerce discount reveals

• Mystery box experiences

---

Performance Considerations

For large surfaces:

• Keep gridResolution moderate

• Avoid excessively large brush sizes

• Use optimized images for overlay

• Avoid heavy nested layouts inside base content

Tip If the scratch area covers most of the screen, prefer lightweight overlay widgets (compressed images, simple containers) to maintain smooth interaction.