# Date utils

> Locale-aware date helpers for React date pickers and calendars: week start, month and weekday names, typed-date parsing, grids and presets.

- Type: React helper (Hooks & Utilities)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add date-utils`
- Docs: https://wingo-ui.com/components/date-utils

## Interaction

Pick a locale and the month grid reorders itself: Sunday first in en-US, Monday first in en-GB and ro-RO, Saturday first in ar-EG, with the names from Intl. Type a date the way people do (9/23, 23/9/26, tomorrow, +3) and see what it parses to. The preset list shows the usual report ranges for today.

## Installation

```bash
npx wingo-ui@latest add date-utils
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/date-utils` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `lib/date-utils.ts`

npm dependencies: `npm i date-fns`

## Usage

```tsx
import { formatDate, getWeekStartsOn, parseDate } from "@/lib/date-utils"

const date = parseDate("9/23", { locale: "en-US" })
formatDate(date, "en-US") // "09/23/2026"
getWeekStartsOn("en-US") // 0 (Sunday)
getWeekStartsOn("ro-RO") // 1 (Monday)
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `locale?` | `string` | `"en-US"` | The demo's locale. Every helper takes an optional locale; pass the one from useLocale so server and browser agree. |
| `text?` | `string` | `""` | The demo's typed date, parsed with parseDate in the locale (English keywords by default, Romanian ones such as maine when the locale is ro-RO). |
| `parseDate?` | `(text: string, options?: { locale?: string; reference?: Date; keywords?: { today?, tomorrow?, yesterday?: string[] } }) => Date \| null` |  | A typed date or null. The locale's field order with . / - or spaces, 1 or 2 digit day and month, a 2 digit year (nearest century) or none (this year), ISO "2026-09-23" in any locale, keywords without case or diacritics, and "+3" / "-2" for days from today. 31.02 is rejected, never rolled over. |

## Parts

### getWeekStartsOn (function)

The first day of the week for a locale, 0 (Sunday) to 6 like date-fns: 0 in en-US, 1 in en-GB and de-DE, 6 in ar-EG. From Intl week info where the browser has it, from a CLDR table where it does not (Firefox).

### getWeekendDays (function)

The weekend days for a locale as weekday numbers: [6, 0] in en-US, [5, 6] in ar-EG. Calendars use it to tint weekends.

### getHourCycle (function)

Whether a locale writes times on a 12 hour ("h12", en-US) or 24 hour clock ("h23", en-GB, de-DE).

### capitalize (function)

Uppercases the first letter in the locale's rules, for month names that Intl writes in lowercase in some languages.

### getMonthNames (function)

The twelve month names from Intl, January first and capitalized, in "long", "short" or "narrow" form. No bundled locale data.

### getWeekdayNames (function)

Weekday names in display order from weekStartsOn, in "long", "short", "min" or "narrow" form. "min" is the two-letter calendar header (Su Mo Tu We Th Fr Sa).

### formatMonthYear (function)

The calendar caption for a month: "September 2026" in en-US.

### getDateOrder (function)

How a locale writes a numeric date: { order, separator, pattern }, e.g. MM/dd/yyyy in en-US and dd.MM.yyyy in de-DE.

### autoFormatDateInput (function)

Inserts the locale's separators while someone types digits into a date field: "0923" becomes "09/23/" in en-US. Text with letters, like "tomorrow", passes through.

### formatDate (function)

A date in the locale, numeric by default ("09/23/2026" in en-US) or with any Intl options ({ dateStyle: "medium" } gives "Sep 23, 2026"). "" for null or an invalid date.

### formatDateRange (function)

A range through Intl formatRange, which writes the shared month and year only once. While only the start is picked it prints the start alone, followed by a dash.

### formatDayLabel (function)

The long spoken form of a day for a day button's aria-label: "Wednesday, September 23, 2026".

### toISODate (function)

"2026-09-23" in local time for hidden form inputs. Never uses toISOString, which converts to UTC and can land on the previous day.

### toISODateTime (function)

"2026-09-23T14:30" in local time, for date and time inputs.

### fromISODate (function)

Reads "2026-09-23" or "2026-09-23T14:30" back into a local Date; null when the text is not one.

### matchesDate (function)

Whether a day matches a DateMatcher or a list of them. Calendars use it for disabled and marked days.

### isDateUnavailable (function)

Whether a day falls outside min or max (by calendar day) or matches disabled. Takes (date, { min?, max?, disabled? }).

### getMonthWeeks (function)

The weeks of a month grid, 7 days each from weekStartsOn, including the neighbor month's days that fill the first and last week. fixedWeeks always returns 6 weeks so the grid never changes height.

### normalizeRange (function)

Puts from before to, swapping a range picked backwards. Nulls stay.

### isInRange (function)

Whether a day is inside a range, both ends included.

### countDays (function)

The days in a range, both ends included (a 3 night hotel stay is 4 days); 0 while the range is incomplete.

### getDatePresets (function)

Single-day presets from a reference day: today, tomorrow, yesterday, nextWeek (same weekday) and nextMonth. Labels are the picker's job.

### getRangePresets (function)

The usual report ranges from a reference day, ends included: last 7 days, this month, last quarter and more. "Last 7 days" ends today.

### parseTime (function)

What someone typed as an "HH:mm" string, or null: "14:30", "1430", "14.30", "2:30 pm", "2p", "12am". Locale-free like <input type="time">.

### formatTime (function)

An "HH:mm" value in the locale: "2:30 PM" in en-US, "14:30" in en-GB. hourCycle forces a 12 or 24 hour clock.

### getDayPeriodLabels (function)

The locale's AM and PM labels, for a time picker's period toggle.

### timeToMinutes (function)

"14:30" to 870 minutes after midnight; null when the value is not a time.

### minutesToTime (function)

870 to "14:30", wrapping around midnight.

### setTime (function)

A new Date on the same day at an "HH:mm" time.

### getTimeOfDay (function)

The "HH:mm" time of a Date.

### DateRange (type)

{ from: Date | null; to: Date | null }, the value of range pickers.

### DateMatcher (type)

What a calendar can disable or mark: a Date, a Date[], { from, to }, { before }, { after }, { dayOfWeek } or (date) => boolean.

### Weekday (type)

0 (Sunday) to 6 (Saturday), like date-fns.

### ParseDateOptions (type)

parseDate's options: locale, reference (the day "tomorrow" counts from) and keywords per language.

## Examples

- **Week start by locale**: Calendar headers and numeric date patterns straight from Intl.
- **Typed dates**: parseDate in en-US with today fixed to Sep 23, 2026; Feb 31 is rejected, never rolled over.
- **Report ranges**: getRangePresets with formatDateRange and countDays, both ends included.
- **Typed times**: parseTime turns loose input into HH:mm; formatTime shows it per locale.

## See also

- [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md))
- [Text match](https://wingo-ui.com/components/text-match) ([Markdown](https://wingo-ui.com/components/text-match.md))
- [useLocale](https://wingo-ui.com/components/use-locale) ([Markdown](https://wingo-ui.com/components/use-locale.md))

---

Canonical: https://wingo-ui.com/components/date-utils
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt