Overview
FormattedDate is the primary way to display dates in the UI. It provides intelligent relative formatting by default ('3 days ago'), auto-updates every minute, and shows absolute dates in tooltips on hover.
Key Features
- Relative dates by default with automatic updates every minute
- Locale-aware formatting (supports all configured languages)
- Automatic tooltips showing absolute date/time on hover
- Configurable absolute format with optional time display
Examples
Relative Dates (Default)
Hover over any relative date to see the absolute date/time in a tooltip.
3 hours ago3 hours ago
3 days ago3 days ago
2 months ago2 months ago
In 1 weekin 6 days
Absolute Dates
Force absolute display when relative dates aren't appropriate.
Date onlyDec 10, 2025
With timeDec 10, 2025 @ 01:27
Short Format
Compact format for space-constrained UIs like timeline cards. Shows 'Nov 15' for dates within the last 12 months, or 'Nov 15, 2025' for older dates.
Recent (within 12 months)Oct 14
Older (over 12 months)Oct 19, 2024
Tooltip Control
Tooltips are automatic for relative dates but can be disabled for email templates, print views, and exports.
With tooltip (hover me)3 days ago
Tooltip disabled3 days ago
Future Dates
Future dates display with 'in X days/weeks' format.
Tomorrowin 23 hours
Next weekin 6 days
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
date | Date | string | required | Date to format (Date object or ISO string) |
style | "relative" | "absolute" | "short" | "relative" | Display style: 'relative' (default), 'absolute', or 'short' |
includeTime | boolean | false | Include time in absolute format and tooltips |
tooltipDisabled | boolean | false | Disable the hover tooltip (for print/email) |
className | string | - | Additional CSS classes for styling |
Usage
import { FormattedDate } from '@/ui/components';
// Relative with tooltip (default)
<FormattedDate date={item.createdAt} />
// Output: "3 days ago" (hover: "Jan 1, 2025 @ 2:45 PM")
// With time in tooltip
<FormattedDate date={item.updatedAt} includeTime />
// Output: "10 minutes ago" (hover: "Jan 3, 2025 @ 2:45 PM")
// Force absolute (no relative)
<FormattedDate date={item.dueDate} style="absolute" />
// Output: "Jan 15, 2025"
// Absolute with time
<FormattedDate date={item.dueDate} style="absolute" includeTime />
// Output: "Jan 15, 2025 @ 2:45 PM"
// Short format (timeline cards, compact UIs)
<FormattedDate date={item.eventDate} style="short" />
// Output: "Nov 15" (within 12 months) or "Nov 15, 2024" (older)
// Email/Print (no tooltip)
<FormattedDate
date={item.createdAt}
style="absolute"
includeTime
tooltipDisabled
/>
// Output: "Jan 1, 2025 @ 2:45 PM"