# Countdown Timer

Countdown timers create urgency by showing customers how much time remains in your promotion or bonus period.

## Prerequisites

1. Enable the **Giveaway Gator Body Tag** in your theme's App Embeds.

## Basic Implementation

Add this HTML element anywhere in your theme:

```html
<div data-gg-countdown-timer></div>
```

## Customization Options

**Data Attributes:**
- `data-gg-countdown-timer` (required) — Initializes the timer.
- `data-template` (optional) — Custom display format.
  - Default: `${days}d ${hours}h ${minutes}m ${seconds}s`
  - Variables: `${days}`, `${hours}`, `${minutes}`, `${seconds}`, `${multiplier}`, `${multiplierX}`
- `data-style` (optional) — Display style (default: `inline`).

## Example Templates

```html
<!-- Basic Timer -->
<div data-gg-countdown-timer></div>

<!-- Custom Format -->
<div data-gg-countdown-timer
  data-template="${days} Days, ${hours}:${minutes}:${seconds}"></div>

<!-- With Multiplier -->
<div data-gg-countdown-timer
  data-template="${multiplierX} Bonus Entries - ${days}d ${hours}h left!"></div>

<!-- Multiplier Only (no ticking countdown) -->
<div data-gg-countdown-timer
  data-template="${multiplierX} Bonus Entries"></div>
```

## CSS Styling

```css
.gg-countdown-timer {
  --gg-timer-bg: #f3f4f6;
  --gg-timer-text: #111827;
  --gg-timer-font-size: 16px;
  --gg-timer-border-radius: 4px;
}
```

## Multiplier-Only Display

If your template only uses `${multiplier}` or `${multiplierX}` — without any time variables (`${days}`, `${hours}`, `${minutes}`, `${seconds}`) — the timer renders once and stops. It won't tick every second, since there's nothing time-based to update.

This is useful when you want to display the current bonus multiplier as a static badge or banner without a countdown. For example:

```html
<div data-gg-countdown-timer
  data-template="${multiplierX} Bonus Entries"></div>
```

This shows "50X Bonus Entries" (or whatever the active multiplier is) without any ticking. The value still updates when the page reloads or every 5 minutes during a revalidation cycle.

## Behavior Notes
- Auto-updates every second (unless using a multiplier-only template — see above)
- Revalidates every 5 minutes for accuracy
- Auto-hides when countdown reaches zero
- Shows bonus multipliers when active
- Prioritizes bonus period countdowns over regular giveaway end times
- If multiple promotions are running, displays the highest active bonus multiplier

## Multiple Promotions

When you have more than one promotion running at the same time, the countdown timer automatically displays the **highest active bonus multiplier** across all promotions. You don't need to configure anything — it picks the best one for your customers.

For example, if Promotion A has a 25x bonus and Promotion B has a 50x bonus, the timer will show "50X."

## Troubleshooting

**Timer shows "1X" instead of the correct multiplier:**
- Verify your bonus period is currently active (not upcoming or ended). Bonus periods use your promotion's timezone, so check the start and end times carefully.
- Make sure the bonus period's dates fall within the promotion's date range. You can check this on the Bonus Periods page — any bonus period with dates outside the promotion window will show an "Outside promo dates" warning badge.
- If you're using `${multiplierX}` or `${multiplier}` in your template, the timer needs an active bonus period to display a value other than 1X.

**Timer not showing at all:**
- Confirm the **Giveaway Gator Body Tag** is enabled in your theme's App Embeds.
- Make sure you have an active promotion with a future end date.
- Check that your HTML element has the `data-gg-countdown-timer` attribute.