> Updated for version 6.0.30

Celestory can keep a date in a variable and calculate with it: add days, count what is left before a deadline, write a date in the player's language. This article is for creators who handle appointments, deadlines, birthdays or a training calendar. It covers the **Date** variable, the seven date blocks and the **Date check** block.

![Above, a graph: Now linked to the from input of Difference between two dates, the deadline variable chosen in the to input, the difference output linked to the text of the Story block. Below, the top of the panel of the deadline Date variable: Tuesday, December 15, 2026, 02:00 PM, that is in 23 days](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdThKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--cc6c12e5add741acd7faa26e09e9b3dc9bd72b2e/aide-visuels--graphe-compte-a-rebours-variable-date.en.png)
*the graph with Now, Difference between two dates and Story, and the panel of the "deadline" Date variable*

## The Date variable

A variable of type **Date** keeps a precise moment: a day and a time. Create it like any variable (see [Choosing a variable type](https://documentation.celestory.io/hc/celestorydoc/articles/1795347775-choosing-a-variable-type)) and choose the **Date** type ("A day and a time, like a deadline or a birthday"). When created, it holds the current minute.

### Entering a date in the panel

Select the variable: the **Visual** panel is titled "Date and time". It offers:

- a calendar, with the **Previous month** and **Next month** buttons and **Today**;
- the **Time**, in two fields, Hours (0 to 23) and Minutes (0 to 59): you must pick a day first;
- **Shortcuts**: **Now**, **Today at midnight** and **Tomorrow** (at the same time);
- a sentence that tells where the date stands ("That is ...") and the time zone it is shown in.

![The Date and time panel with the calendar, the time and the shortcuts](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBcmNKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--aa73f86087c3a9e05e8a72731404b87e21b5e22a/aide-visuels--variable-panneau-date-complet.en.png)
*The Date and time panel with the calendar, the time and the shortcuts.*

If the stored value is not a valid date, the panel says so ("This date cannot be read") and offers **Replace with now**.

### Showing a date in a text

Write `{{deadline}}` in a text: the player reads the date and the time in words, in their language (for example "October 15, 2026 at 02:00 PM" in American English; the exact layout can vary slightly from one browser to another). The language is the one the player picked, otherwise the one the project is written in, otherwise the one of the device. An invalid date is written as an empty text. To choose the format, use the **Format a date** block.

## The date blocks

Add them with a right click on the graph, **Add a block**, then type the name in the **Search** field. Date inputs accept a Date variable, the output of another date block, or a date entered directly. By default, a date input already holds a valid date: the minute you added the block.

| Block | Inputs | Outputs | Example |
|---|---|---|---|
| Now | none | date | The clock of the player's device when the block is read |
| Add to a date | date, amount, unit, time zone | result | Now + 7 days = the reminder date |
| Difference between two dates | from, to, unit, time zone | difference | Days between Now and the deadline |
| Compare two dates | (stream), first date, second date, precision, time zone | first is before, same, first is after | Branch the story depending on whether the date has passed |
| Format a date | date, format, custom pattern, language, time zone | text | "Friday 2 October 2026" |
| Extract from a date | date, time zone | year, month (1-12), day of the month, day of the week (1 = Monday), hour, minute | Find out whether it is Monday |
| Date from numbers | year, month (1-12), day of the month, hour, minute, time zone | date | Build December 25, 2026 at 8:30 pm |

### Shared settings

- **Unit** (Add, Difference): seconds, minutes, hours, days, weeks, months or years. Default: days;
- **Time zone**: "player's time zone" (default) or "UTC";
- **Precision** (Compare): exact, same second, same minute, same hour, same day, same month or same year;
- **Format** (Format): short date, long date, full date with weekday, time, date and time (default), weekday, month, ISO 8601 or custom pattern.

### What each block does

- **Add to a date** accepts a negative amount to go back. Adding one month to January 31 gives February 28 (February 29 in a leap year): the month stops at its last day.
- **Difference between two dates** counts whole units and gives a negative number when "to" is before "from". From October 2 at 0:00 to October 12 at 11:59 pm, there are 10 days.
- **Compare two dates** is a stream block: it follows the "first is before", "same" or "first is after" output. If the chosen output is connected to nothing, the story stops there.
- **Format a date** writes the date in the **language** you give (a code such as `fr` or `en-GB`); if you leave it empty, it uses the player's language, then the project's, then the device's. The **custom pattern** follows the Moment library codes: `dddd D MMMM YYYY` gives "Friday 2 October 2026" in English. An empty pattern gives the date and time.
- **Extract from a date** gives six numbers. The day of the week goes from 1 (Monday) to 7 (Sunday).
- **Date from numbers** refuses a date that does not exist (month 13, February 30).

## Date check: the reader's clock

The **Date check** block (stream input and **date** input) follows the **before** output while the date has not come, and the **after** output once it has passed. It reads the clock of the device, never the network. If the input holds no valid date, it follows the **before** output. For a finer test (same day, same month), prefer **Compare two dates**.

The **Today's date** block is older: its **date** and **date with time** outputs are texts, not dates. To calculate, use **Now**.

## Example: a countdown to an event

1. Create a **Date** variable named `deadline` and set it in the panel.
2. Add a **Now** block and a **Difference between two dates** block.
3. Connect the **date** output of **Now** to the **from** input.
4. In the **to** input, choose the `deadline` variable.
5. Leave the unit on "days".
6. To show this number to the player, use a block that displays text and accepts `{{name}}` slots, such as **Narrator** (Chatbot) or **Dialogue** (Visual Novel): write for example `Only {{days}} days left!` in its text. A **days** input appears on the block: connect the **difference** output to it. The number shows as is, in whole days. The **Story** block does not fit: its text input does not accept a number.

![The countdown graph with the three blocks connected](https://chatwoot.fr.nocodespacelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBcmdKIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--2cef27b5e8211bc541f75328b657a685f3c179d1/aide-visuels--graphe-compte-a-rebours.en.png)
*The countdown graph with the three blocks connected.*

The player sees the number of days left, calculated each time the block is read.

## Time zones and pitfalls

- A date is stored in UTC: it is the same moment for everyone, each person reads it in their own time zone. The panel shows it in your time zone.
- With "player's time zone", a player in Tokyo and a player in Paris can get different days for the same date. Choose "UTC" for the same result everywhere.
- Dates come from the clock of the player's device.
- A **List** cannot hold dates.

## Troubleshooting

These error messages, written in English, point to a date block that cannot do its calculation while the story is played.

| Message | Solution |
|---|---|
| the input "..." holds no valid date | Connect a Now block, a Date variable or another date block, or pick a date |
| ... is not a date. Month goes from 1 to 12, hour from 0 to 23, minute from 0 to 59 | Fix the numbers of Date from numbers (February 30 does not exist) |

## See also

- [🟦 Today's date](https://documentation.celestory.io/hc/celestorydoc/articles/en-blocks-todays-date-ebe2dd)
- [🟪 Date check](https://documentation.celestory.io/hc/celestorydoc/articles/en-blocks-date-check-5f394b)
- [📅 Schedule a meeting](https://documentation.celestory.io/hc/celestorydoc/articles/en-discover-celestory-schedule-a-meeting-d8d605)
- [Choosing a variable type](https://documentation.celestory.io/hc/celestorydoc/articles/1795347775-choosing-a-variable-type)
- [Percentage and Duration variables](https://documentation.celestory.io/hc/celestorydoc/articles/1795347800-percentage-and-duration-variables)
