# @solid-primitives/date

> Collection of reactive primitives and utility functions, providing easier ways to deal with dates in SolidJS

Latest version **2.1.8** (published 2026-07-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @solid-primitives/date
pnpm add @solid-primitives/date
yarn add @solid-primitives/date
bun add @solid-primitives/date
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.8 |
| Published | 2026-07-04 |
| First published | 2022-01-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 30.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1559 |
| Author | Damian Tarnawski @thetarnav |
| Maintainers | davedbase, lexlohr, thetarnav. |
| Keywords | date, time, solid, primitives |

## Links

- npm: https://www.npmjs.com/package/@solid-primitives/date
- Repository: https://github.com/solidjs-community/solid-primitives
- Homepage: https://primitives.solidjs.community/package/date
- Issues: https://github.com/solidjs-community/solid-primitives/issues
- npm.io page: https://npm.io/package/@solid-primitives/date

## Dependencies (3)

- [@solid-primitives/memo](https://npm.io/package/@solid-primitives/memo.md) ^1.5.1
- [@solid-primitives/timer](https://npm.io/package/@solid-primitives/timer.md) ^1.4.4
- [@solid-primitives/utils](https://npm.io/package/@solid-primitives/utils.md) ^6.4.1

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 2.1.8 (latest) — 2026-07-04
- 3.0.0-next.3 (next) — 2026-08-12
- 2.0.9-beta.1 (beta) — 2023-03-03
- 3.0.0-next.2 — 2026-07-18
- 3.0.0-next.1 — 2026-07-04
- 3.0.0-next.0 — 2026-06-26
- 2.1.7 — 2026-06-04
- 2.1.6 — 2026-02-24
- 2.1.5 — 2026-02-21
- 2.1.4 — 2025-08-28
- 2.1.3 — 2025-06-29
- 2.1.2 — 2025-04-27
- 2.1.1 — 2025-03-13
- 2.1.0 — 2025-01-22
- 2.0.24 — 2024-10-27
- … 27 more at https://npm.io/package/@solid-primitives/date/versions

## README

<p>
  <img width="100%" src="https://assets.solidjs.com/banner?type=Primitives&background=tiles&project=Date" alt="Solid Primitives Date">
</p>

# @solid-primitives/date

[![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/date?style=for-the-badge)](https://bundlephobia.com/package/@solid-primitives/date)
[![size](https://img.shields.io/npm/v/@solid-primitives/date?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/date)
[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-3.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)

Collection of reactive primitives and utility functions, providing easier ways to deal with dates in SolidJS.

- [`createDate`](#createdate) - Creates a reactive `Date` signal.
- [`createDateNow`](#createdatenow) - Creates an autoupdating and reactive `new Date()`.
- [`createTimeDifference`](#createtimedifference) - Provides a reactive time difference _(in ms)_ signal.
- [`createTimeDifferenceFromNow`](#createtimedifferencefromnow) - Provides a autoupdating, reactive time difference _(in ms)_ from **now** as a signal.
- [`createTimeAgo`](#createtimeago) - Provides a reactive, formatted, autoupdating date difference in relation to **now**.
- [`createCountdown`](#createcountdown) - Provides a reactive broken down time remaining Store.
- [`createCountdownFromNow`](#createcountdownfromnow) - Provides a reactive, autoupdating _(from **now**)_, broken down "time remaining" as a Store.
- \+ [some non-reactive date-related utility functions](#utility-functions).

## Installation

```
npm install @solid-primitives/date
# or
yarn add @solid-primitives/date
```

## Reactive Primitives:

### `createDate`

Creates a reactive `Date` signal.

```ts
const [date, setDate] = createDate(1641408329089);

date(); // T: Date

setDate("2020 1 11");

// passed initial value can be reactive
const [timestamp, setTimestamp] = createSignal(1641408329089);
const [date, setDate] = createDate(timestamp);

setTimestamp(1341708325070); // will update the date
```

### `createDateNow`

Creates an autoupdating and reactive `new Date()`.

```ts
import { createDateNow } from "@solid-primitives/date";

// updates every second:
const [now] = createDateNow(1000);

// reactive timeout value
const [timeout, setTimeout] = createSignal(500);
const [now] = createDateNow(timeout);

// won't autoupdate:
const [now, update] = createDateNow(() => false);

// update manually:
update();
```

### `createTimeDifference`

Provides a reactive time difference _(in ms)_ signal.

```ts
// the arguments can be reactive
const [target, setTarget] = createSignal(1641408329089);
const [diff, { from, to }] = createTimeDifference("2020 1 11", target);
diff(); // T: number
from(); // T: Date
to(); // T: Date
```

### `createTimeDifferenceFromNow`

Provides a autoupdating, reactive time difference _(in ms)_ from **now** as a signal.

```ts
const [target, setTarget] = createSignal(1641408329089);
const [diff, { target, now, update }] = createTimeDifferenceFromNow(target);
diff(); // T: number
target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// you can pass a custom interval (number or function or false)
createTimeDifferenceFromNow(target, diff => (diff > 100000 ? 30000 : 1000));
```

### `createTimeAgo`

Provides a reactive, formatted date difference in relation to now.

```ts
import { createTimeAgo, createDate } from "@solid-primitives/date";

const [myDate, setMyDate] = createDate("Jun 28, 2021");
const [timeago, { target, now, update, difference }] = createTimeAgo(myDate);
// => 5 months ago

timeago(); // => 5 months ago
difference(); // T: number
target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// use custom libraries to change formatting:
import { formatRelative } from "date-fns";
const [timeago] = createTimeAgo(1577836800000, {
  min: 10000,
  interval: 30000,
  relativeFormatter: (target, now) => formatRelative(target, now),
});
// => last Monday at 9:25 AM
```

### `createCountdown`

Provides a reactive broken down time remaining Store.

```ts
const [to, setTo] = createSignal(1641408329089);
const countdown = createCountdown("2020 1 11", to);

countdown.minutes; // e.g. 5
countdown.hours; // e.g. 1
countdown.seconds; // e.g. 48
```

### `createCountdownFromNow`

Provides a reactive, autoupdating _(from **now**)_, broken down "time remaining" as a Store.

```ts
// target date may be reactive
const [to, setTo] = createSignal(1641408329089);
const [countdown, { now, target, update }] = createCountdownFromNow(to);

countdown.minutes; // e.g. 5
countdown.hours; // e.g. 1
countdown.seconds; // e.g. 48

target(); // T: Date
now(); // T: Date
// manual update (automatic one can be disabled by passing false)
update();

// you can pass a custom interval (number or function or false)
createCountdownFromNow(to, diff => (diff > 100000 ? 30000 : 1000));
```

## Utility Functions

### `getDate`

```ts
/**
 * @param init timestamp `number` | date `string` | `Date` instance
 * @returns `Date` instance
 */
const getDate = (init: DateInit): Date
```

### `getTime`

```ts
/**
 * @param init timestamp `number` | date `string` | `Date` instance
 * @returns timestamp `number`
 */
const getTime = (init: DateInit): number
```

### `getDateDifference`

Get the time difference between two dates _[ms]_

```ts
const getDateDifference = (from: Date, to: Date): number
```

### `getCountdown`

Provides broken down time remaining from a time difference.

```ts
/**
 * @param difference time difference between two dates *[ms]*
 * @returns countdown object with keys: `days`, `hours`, `minutes`, etc.
 */
const getCountdown = (difference: number): Countdown
```

### `formatDate`

Apply basic formatting to a `Date` instance.

```ts
const formatDate = (date: Date): string

// example
const date = new Date("2020 1 11")
formatDate(date) // => '2020-01-10'
```

### `formatDateRelative`

Applies relative time formatting based on a time difference from **now**.

```ts
/**
 * @param difference time difference between a date and now *[ms]*
 * @param messages custom messages for changing formatting
 * @returns formatted string, e.g. *"2 seconds ago"*, *"in 3 weeks"*...
 */
function formatDateRelative(difference: number, messages?: Partial<RelativeFormatMessages>): string;
```

## Demo

https://codesandbox.io/s/solid-date-hjxui?file=/index.tsx

## Changelog

See [CHANGELOG.md](./CHANGELOG.md)

## Acknowledgement

- [VueUse — useTimeAgo](https://vueuse.org/core/usetimeago/)

---
_Source: https://npm.io/package/@solid-primitives/date · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._