# Countdown

Countdown is used to ensure that a "countdown" to a specified end time is
displayed in a consistent format. No text styling is applied to Countdown; it is
only concerned with the text content that will be presented.

## Design & usage guidelines

Use Countdown when:

* There is a need to make a deadline, such as time left to update important
  details about your account, apparent to the user.
* There is a desire to convey urgency to the user for conversion optimization
  purposes, such as in a time-bound promotional offer.

When choosing which units of time to display via the `granularity` property,
consider the time range that the countdown will start at, and the required level
of urgency. For example, you may not want to display a 4-day countdown using
only seconds; and conversely, a 2-hour countdown would not be conducive to
rendering with only days and hours.

## Content guidelines

Countdown only displays numbers and the units of time that it represents. You
can choose to show or hide the units themselves, in which case the units are
removed and only the `:` between digits remains.

Consider the context of the countdown and whether the user will have enough
context to interpret appropriately without labeled units when making the
decision on whether to show or hide the units.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `date` | `Date | number | string` | Yes | — | The date that is being counted down to. Value for date as a `string` should be in ISO 8601 format. |
| `granularity` | `GranularityOptions` | No | `dhms` | Defines the time format presented (e.g., dhms will show days, hours, minutes, and seconds) |
| `onComplete` | `() => void` | No | — | Callback when the countdown is done |
| `showUnits` | `boolean` | No | — | Whether or not to present the unit of time to the user, or just the raw numbers. |