Date and time formatting for applications. Use when displaying dates, timestamps, or formatting time in UI components. Use centralized utilities instead of native JS date methods. Triggers on date, time, timestamp, formatDate, formatTime, toLocaleDateString, toLocaleString, dateUtils, locale, format, display date, show time, datetime, calendar.
Guidelines for consistent date and time formatting across applications.
Use centralized date utilities for consistency:
// ❌ AVOID - Inconsistent across locales/platforms
date.toLocaleDateString()
date.toLocaleString()
new Intl.DateTimeFormat().format(date)
// ✅ CORRECT - Use centralized utility
import { formatDate } from '@{scope}/shared/src/utils/dateUtils';
formatDate(date, { hideSeconds: true });
| Function | Use Case | Example Output |
|---|---|---|
formatDate(date, options?) | Full date and time | 2024/01/15, 14:30 |
formatTime(date, options?) | Time only | 14:30:45 |
formatRelativeDate(date) |
| Relative display |
Today, Yesterday |
formatDistanceToNow(date) | Time distance | 2 hours ago |
formatDateFns(date, format?) | Custom format | Based on template |
import { formatDate } from '@{scope}/shared/src/utils/dateUtils';
// Hide year if current year, hide seconds
<Text>
{formatDate(item.createdAt, { hideTheYear: true, hideSeconds: true })}
</Text>
// Use format template
{formatDate(item.timestamp, { formatTemplate: 'yyyy-LL-dd HH:mm' })}
import { useFormatDate } from '@{scope}/kit/src/hooks/useFormatDate';
function MyComponent() {
const { formatDate } = useFormatDate();
return <Text>{formatDate(date, { hideSeconds: true })}</Text>;
}
interface IFormatDateOptions {
hideYear?: boolean; // Always hide year
hideMonth?: boolean; // Always hide month
hideTheYear?: boolean; // Hide year if current year
hideTheMonth?: boolean; // Hide month if current month
hideTimeForever?: boolean; // Hide time portion
hideSeconds?: boolean; // Hide seconds (HH:mm)
formatTemplate?: string; // Custom date-fns format
}
For comprehensive date formatting rules and examples, see date-formatting.md.
Topics covered:
| Purpose | File Path |
|---|---|
| Core utilities | packages/shared/src/utils/dateUtils.ts |
| React hook | packages/kit/src/hooks/useFormatDate.ts |
| Locale mapping | packages/shared/src/locale/dateLocaleMap.ts |
/i18n - Internationalization and locale handling/coding-patterns - General coding patterns