# 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.

{% embed url="<https://www.youtube.com/watch?v=FYp5lN5-gWU>" %}

**Watch this on Youtube:** [**https://www.youtube.com/watch?v=FYp5lN5-gWU**](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

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Foe4PSIjmxsoHeBXEPQR7%2Fscratch%20card.png?alt=media&#x26;token=f98fb930-df46-491d-abf5-415835f2e838" alt="Two rectangular scratch cards displayed inside a rounded light-gray container. The left card is completely unscratched with a silver textured surface, while the right card is partially scratched, revealing a golden “COUPON” label with colorful confetti and a scratch tool at the edge. The title “Scratch Card” appears below the cards."><figcaption><p>Scratch Card widget showing an unscratched state and a fully revealed reward state.</p></figcaption></figure>

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.

{% hint style="warning" %}
Both `overlay` and `base` child groups are mandatory. If one is not provided, the widget will not render.
{% endhint %}

***

### 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.                                                                                    |

{% hint style="warning" %}
**Warning:** Setting `isScratchingEnabled` to false will completely disable interaction, even if other scratch properties are configured.
{% endhint %}

{% hint style="info" %}
**Tip** For most use cases, keep `gridResolution` between 80–120. Extremely high values may impact performance on low-end devices.
{% endhint %}

***

#### 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.

{% hint style="info" %}
**Tip** Avoid combining long animation durations with high grid resolution for large scratch surfaces, as it may increase frame workload.
{% endhint %}

***

### 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`

{% hint style="info" %}
**Tip** `onScratchComplete` fires only once per widget lifecycle. If you need repeatable behavior, the widget must be rebuilt.
{% endhint %}

***

### 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

{% hint style="success" %}
**Tip** If the scratch area covers most of the screen, prefer lightweight overlay widgets (compressed images, simple containers) to maintain smooth interaction.
{% endhint %}