# <motion-countdown>

Countdown timer with animated digit transitions. Supports flip (default) and
roll (slot-machine) modes. Customisable format, labels, and target date.

**Use it for:** the time left until a launch, an event start or the end of
a sale, shown in days, hours, minutes and seconds.

**Avoid it for:** elapsed time or a stopwatch, because it only counts down
and stays at zero when the time is up. To count a number up once, use
`motion-counter`.

**Accessibility:** the numbers and unit labels are plain text, and the `:`
separators are hidden from screen readers. There is no live region, so
screen readers do not announce each second. In `roll` mode the columns of
the numbers 0 to 9 are `aria-hidden`, and screen readers read the current
value of each unit from a visually hidden copy.

**Reduced motion:** the timer still updates every second, but each digit
changes in place with no flip or roll. `motion-start` and `motion-finish`
fire as usual, and `pause()`, `play()` and `cancel()` control the timer.

**Common mistakes:** setting a new `to` after the time is up; the timer has
stopped, so call `play()` to count down again. Leaving `days` out of
`format` when the target is more than a day away; hours only go from 0 to
23, so the days are lost.

Docs: https://www.motion-components.dev/docs/components/motion-countdown/

## Install

```js
import 'motion-components/motion-countdown'
```

Or without a build step:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/motion-components@1/dist/motion-countdown.js/+esm"></script>
```

## Example

```html
<motion-countdown to="2026-12-31T23:59:59" format="days hours minutes seconds" roll></motion-countdown>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `to` | `string` | `''` | ISO date string the countdown counts down to. |
| `format` | `string` | `'days hours minutes seconds'` | Space-separated list of units to display: `days`, `hours`, `minutes`, `seconds`. |
| `labels` | `boolean` | `true` | Whether to show unit labels (Days, Hours, etc.) beneath each value. Set `labels="false"` to turn it off. |
| `roll` | `boolean` | `false` | Enable slot-machine roll animation instead of the default flip. |

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `playState` | `'idle' \| 'running' \| 'paused' \| 'finished'` | Current state: `'idle'`, `'running'`, `'paused'` or `'finished'`. |
| `finished` | `Promise<void>` | Resolves when the current run settles. A new run replaces the promise. |

## Methods

| Method | Description |
| --- | --- |
| `play()` | Starts the animation, or resumes it when paused. Resolves once the run settles. Under `prefers-reduced-motion: reduce` the final state is applied immediately without animating. |
| `pause()` | Holds the animation at its current position. No-op unless running. |
| `finish()` | Jumps to the final state and settles. Fires `motion-finish`. |
| `cancel()` | Reverts to the initial state and returns to idle. Fires `motion-cancel`. |

## Events

The `motion-*` events bubble and are composed.

| Event | Description |
| --- | --- |
| `motion-start` | When a run starts. |
| `motion-finish` | Once when the time is up, or when `finish()` jumps to the end. |
| `motion-cancel` | When `cancel()` stops a run and resets it. |

## CSS custom properties

| Property | Description |
| --- | --- |
| `--mc-countdown-size` | Font size of the digits. Default `3.5rem`. |
| `--mc-countdown-color` | Digit color. Default `currentColor`. |
| `--mc-countdown-gap` | Space between units. Default `0.75rem`. |
| `--mc-countdown-label-size` | Font size of the unit labels. Default `0.65rem`. |
| `--mc-countdown-label-color` | Unit label color. Default `currentColor`. |