Date Handling Pattern | Bootspring Docs

Work with dates, times, and timezones using date-fns for consistent, type-safe date manipulation.

Overview#

Date handling is one of the most error-prone areas in web development. This pattern provides utilities for formatting, parsing, timezone conversion, and date comparisons using the battle-tested date-fns library.

When to use:

Displaying dates in user interfaces
Date range selection and filtering
Timezone conversions
Relative time display ("2 hours ago")
Calendar components
Date validation

Key features:

Consistent date formatting
Timezone-aware operations
Relative time formatting
Date range utilities
React components
Zod validation

Code Example#

Core Utilities#

// lib/dates.ts
import {
  format,
  formatDistanceToNow,
  parseISO,
  isValid,
  startOfDay,
  endOfDay,
  addDays,
  subDays,
  differenceInDays,
  isBefore,
  isAfter,
  isSameDay
} from 'date-fns'
import { formatInTimeZone, toZonedTime } from 'date-fns-tz'

// Format date for display
export function formatDate(
  date: Date | string,
  pattern = 'MMM d, yyyy'
): string {
  const d = typeof date === 'string' ? parseISO(date) : date
  return isValid(d) ? format(d, pattern) : 'Invalid date'
}

// Format datetime
export function formatDateTime(date: Date | string): string {
  return formatDate(date, 'MMM d, yyyy h:mm a')
}

// Relative time (e.g., "2 hours ago")
export function timeAgo(date: Date | string): string {
  const d = typeof date === 'string' ? parseISO(date) : date
  return formatDistanceToNow(d, { addSuffix: true })
}

// Format with timezone
export function formatWithTimezone(
  date: Date | string,
  timezone: string,
  pattern = 'MMM d, yyyy h:mm a zzz'
): string {
  const d = typeof date === 'string' ? parseISO(date) : date
  return formatInTimeZone(d, timezone, pattern)
}

// Parse user input
export function parseDate(input: string): Date | null {
  const parsed = parseISO(input)
  return isValid(parsed) ? parsed : null
}

Date Range Utilities#

// lib/dates.ts
export type DateRangePreset =
  | 'today'
  | 'yesterday'
  | 'last7days'
  | 'last30days'
  | 'thisMonth'
  | 'lastMonth'

export function getDateRange(range: DateRangePreset): {
  start: Date
  end: Date
} {
  const now = new Date()
  const end = endOfDay(now)

  switch (range) {
    case 'today':
      return { start: startOfDay(now), end }
    case 'yesterday':
      return {
        start: startOfDay(subDays(now, 1)),
        end: endOfDay(subDays(now, 1))
      }
    case 'last7days':
      return { start: startOfDay(subDays(now, 6)), end }
    case 'last30days':
      return { start: startOfDay(subDays(now, 29)), end }
    case 'thisMonth':
      return {
        start: startOfDay(new Date(now.getFullYear(), now.getMonth(), 1)),
        end
      }
    case 'lastMonth':
      return {
        start: startOfDay(new Date(now.getFullYear(), now.getMonth() - 1, 1)),
        end: endOfDay(new Date(now.getFullYear(), now.getMonth(), 0))
      }
  }
}

// Check if date is within range
export function isInRange(
  date: Date,
  start: Date,
  end: Date
): boolean {
  return !isBefore(date, start) && !isAfter(date, end)
}

// Get number of days between dates
export function daysBetween(start: Date, end: Date): number {
  return differenceInDays(end, start)
}

Timezone Handling#

// lib/timezone.ts
import { toZonedTime, fromZonedTime, formatInTimeZone } from 'date-fns-tz'

// Get user's timezone
export function getUserTimezone(): string {
  return Intl.DateTimeFormat().resolvedOptions().timeZone
}

// Convert UTC to user's timezone
export function toUserTime(utcDate: Date, timezone?: string): Date {
  const tz = timezone ?? getUserTimezone()
  return toZonedTime(utcDate, tz)
}

// Convert user's local time to UTC
export function toUTC(localDate: Date, timezone?: string): Date {
  const tz = timezone ?? getUserTimezone()
  return fromZonedTime(localDate, tz)
}

// Format in specific timezone
export function formatInTz(
  date: Date,
  timezone: string,
  pattern = 'yyyy-MM-dd HH:mm:ss zzz'
): string {
  return formatInTimeZone(date, timezone, pattern)
}

// Get timezone options for select
export const timezones = Intl.supportedValuesOf('timeZone').map(tz => ({
  value: tz,
  label: tz.replace(/_/g, ' ')
}))

Date Input Component#

// components/DateInput.tsx
'use client'

import { useState } from 'react'
import { format, parse, isValid } from 'date-fns'

interface DateInputProps {
  value?: Date
  onChange: (date: Date | null) => void
  min?: Date
  max?: Date
  disabled?: boolean
}

export function DateInput({
  value,
  onChange,
  min,
  max,
  disabled
}: DateInputProps) {
  const [inputValue, setInputValue] = useState(
    value ? format(value, 'yyyy-MM-dd') : ''
  )

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const newValue = e.target.value
    setInputValue(newValue)

    if (newValue === '') {
      onChange(null)
      return
    }

    const parsed = parse(newValue, 'yyyy-MM-dd', new Date())
    if (isValid(parsed)) {
      if (min && parsed < min) return
      if (max && parsed > max) return
      onChange(parsed)
    }
  }

  return (
    <input
      type="date"
      value={inputValue}
      onChange={handleChange}
      min={min ? format(min, 'yyyy-MM-dd') : undefined}
      max={max ? format(max, 'yyyy-MM-dd') : undefined}
      disabled={disabled}
      className="rounded-md border px-3 py-2 focus:outline-none focus:ring-2 focus:ring-blue-500"
    />
  )
}

Relative Time Component#

// components/RelativeTime.tsx
'use client'

import { useEffect, useState } from 'react'
import { formatDistanceToNow } from 'date-fns'
import { formatDateTime } from '@/lib/dates'

interface RelativeTimeProps {
  date: Date | string
  updateInterval?: number // milliseconds
}

export function RelativeTime({
  date,
  updateInterval = 60000
}: RelativeTimeProps) {
  const dateObj = typeof date === 'string' ? new Date(date) : date
  const [relative, setRelative] = useState(
    formatDistanceToNow(dateObj, { addSuffix: true })
  )

  useEffect(() => {
    const timer = setInterval(() => {
      setRelative(formatDistanceToNow(dateObj, { addSuffix: true }))
    }, updateInterval)

    return () => clearInterval(timer)
  }, [dateObj, updateInterval])

  return (
    <time
      dateTime={dateObj.toISOString()}
      title={formatDateTime(dateObj)}
      className="text-muted-foreground"
    >
      {relative}
    </time>
  )
}

Date Range Picker#

// components/DateRangePicker.tsx
'use client'

import { useState } from 'react'
import { format } from 'date-fns'
import { Calendar as CalendarIcon } from 'lucide-react'
import { DayPicker, DateRange } from 'react-day-picker'
import { cn } from '@/lib/utils'

interface DateRangePickerProps {
  value?: DateRange
  onChange: (range: DateRange | undefined) => void
  placeholder?: string
}

export function DateRangePicker({
  value,
  onChange,
  placeholder = 'Select date range'
}: DateRangePickerProps) {
  const [open, setOpen] = useState(false)

  const formatRange = (range?: DateRange) => {
    if (!range?.from) return placeholder
    if (!range.to) return format(range.from, 'MMM d, yyyy')
    return `${format(range.from, 'MMM d')} - ${format(range.to, 'MMM d, yyyy')}`
  }

  return (
    <div className="relative">
      <button
        onClick={() => setOpen(!open)}
        className={cn(
          'flex items-center gap-2 rounded-md border px-3 py-2 text-sm',
          !value?.from && 'text-gray-500'
        )}
      >
        <CalendarIcon className="h-4 w-4" />
        {formatRange(value)}
      </button>

      {open && (
        <div className="absolute top-full mt-2 bg-white border rounded-lg shadow-lg z-50">
          <DayPicker
            mode="range"
            selected={value}
            onSelect={(range) => {
              onChange(range)
              if (range?.from && range?.to) setOpen(false)
            }}
            numberOfMonths={2}
          />
        </div>
      )}
    </div>
  )
}

Date Validation with Zod#

// lib/validation/dates.ts
import { z } from 'zod'
import { parseISO, isValid, isFuture, isPast, isAfter } from 'date-fns'

// Date string schema
export const dateStringSchema = z.string().refine(
  val => isValid(parseISO(val)),
  { message: 'Invalid date format' }
)

// Future date schema
export const futureDateSchema = dateStringSchema.refine(
  val => isFuture(parseISO(val)),
  { message: 'Date must be in the future' }
)

// Past date schema
export const pastDateSchema = dateStringSchema.refine(
  val => isPast(parseISO(val)),
  { message: 'Date must be in the past' }
)

// Date range schema
export const dateRangeSchema = z.object({
  from: dateStringSchema,
  to: dateStringSchema
}).refine(
  ({ from, to }) => isAfter(parseISO(to), parseISO(from)),
  { message: 'End date must be after start date' }
)

// Age validation
export function validateAge(birthDate: Date, minAge: number): boolean {
  const today = new Date()
  const age = today.getFullYear() - birthDate.getFullYear()
  const monthDiff = today.getMonth() - birthDate.getMonth()

  if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birthDate.getDate())) {
    return age - 1 >= minAge
  }
  return age >= minAge
}

// Usage with forms
const bookingSchema = z.object({
  checkIn: futureDateSchema,
  checkOut: dateStringSchema
}).refine(
  data => isAfter(parseISO(data.checkOut), parseISO(data.checkIn)),
  { message: 'Check-out must be after check-in', path: ['checkOut'] }
)

Usage Instructions#

Install date-fns: npm install date-fns date-fns-tz
Create utility file: Add common date functions to lib/dates.ts
Use consistent formatting: Always use the same format patterns
Handle timezones: Store UTC in database, display in user timezone
Validate inputs: Use Zod schemas for date validation

Best Practices#

Store UTC in database - Always store dates in UTC
Display in user timezone - Convert to local time for display
Use ISO strings for API - Transfer dates as ISO 8601 strings
Validate date ranges - Ensure end date is after start date
Handle invalid dates - Check with isValid() before formatting
Use date-fns tree-shaking - Import only what you need
Consider locale - Use locale-aware formatting when needed
Update relative times - Refresh "time ago" displays periodically

Formatting - Number and text formatting
Validation - Input validation with Zod
Forms - Form handling with dates