Date Formatting Skill

This skill ensures consistent date and time formatting across the OneKey app, respecting user locale settings.

Usage

Use this skill when:

• Displaying dates or times in UI components
• Formatting timestamps from API responses
• Ensuring dates follow the app's language/locale settings
• Converting date strings for display

Core Rules

NEVER use native JavaScript date methods

// ❌ FORBIDDEN - Does not respect app settings
date.toLocaleDateString()
date.toLocaleString()
date.toISOString()
new Intl.DateTimeFormat().format(date)

ALWAYS use OneKey's date utilities

// ✅ CORRECT - Follows app locale settings
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
formatDate(date, { hideSeconds: true });

Available Functions

From @onekeyhq/shared/src/utils/dateUtils

Function	Description	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, 2024/01/15
formatDistanceToNow(date)	Time distance	2 days ago, 5 minutes ago
formatDateFns(date, format?)	Custom format	Based on format template

Options Reference

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 instead of HH:mm:ss)
  formatTemplate?: string;   // Custom date-fns format template
}

Format Templates

Common date-fns format tokens:

Token	Description	Example
yyyy	4-digit year	2024
LL	2-digit month	01
dd	2-digit day	15
HH	24-hour hours	14
mm	Minutes	30
ss	Seconds	45
PPP	Full date	January 15, 2024

Common Patterns

Transaction/History Lists

import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';

// Standard format, hide seconds
<SizableText>{formatDate(item.createdAt, { hideSeconds: true })}</SizableText>

Smart Year Display

// Hide year if it's the current year
<SizableText>
  {formatDate(item.date, { hideTheYear: true, hideSeconds: true })}
</SizableText>

Custom Format

// Custom format template
<SizableText>
  {formatDate(item.timestamp, { formatTemplate: 'yyyy-LL-dd HH:mm' })}
</SizableText>

Relative Time

import { formatDistanceToNow } from '@onekeyhq/shared/src/utils/dateUtils';

// "2 hours ago", "5 minutes ago"
<SizableText>{formatDistanceToNow(item.updatedAt)}</SizableText>

React Hook (for dynamic updates)

import useFormatDate from '@onekeyhq/kit/src/hooks/useFormatDate';

function MyComponent() {
  const { formatDate, formatDistanceToNow } = useFormatDate();

  return (
    <SizableText>{formatDate(date, { hideSeconds: true })}</SizableText>
  );
}

Locale-Aware Format

The date utilities automatically detect the app locale and adjust format:

// Automatically uses correct format based on locale:
// 'en-US' → 'LL/dd/yyyy, HH:mm:ss' (01/15/2024)
// 'zh-CN' → 'yyyy/LL/dd, HH:mm:ss' (2024/01/15)
// 'de'    → 'LL/dd/yyyy, HH:mm:ss'

Real-World Examples

Example 1: ReferFriends List

// File: packages/kit/src/views/ReferFriends/pages/YourReferred/index.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';

<SizableText size="$bodyMd" color="$textSubdued">
  {item.createdAt
    ? formatDate(item.createdAt, { formatTemplate: 'yyyy-LL-dd HH:mm' })
    : ''}
</SizableText>

Example 2: Transaction History

// File: packages/kit/src/components/TxHistoryListView/index.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';

formatDate(new Date(date), {
  hideTheYear: true,
  hideSeconds: true,
})

Example 3: Redemption History

// File: packages/kit/src/views/Redemption/pages/RedemptionHistory.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';

<SizableText size="$bodyMd" color="$textSubdued">
  {formatDate(item.redeemedAt, { hideSeconds: true })}
</SizableText>

Key Files

Purpose	File Path
Core utilities	packages/shared/src/utils/dateUtils.ts
React hook	packages/kit/src/hooks/useFormatDate.ts
Locale hook	packages/kit/src/hooks/useLocaleVariant.ts
Locale mapping	packages/shared/src/locale/dateLocaleMap.ts
App locale	packages/shared/src/locale/appLocale.ts

Troubleshooting

Date shows wrong locale

Ensure you're using @onekeyhq/shared/src/utils/dateUtils instead of native methods. The utility automatically reads from appLocale.getLocale().

Need to update when locale changes

Use the useFormatDate hook in React components for reactive updates:

import useFormatDate from '@onekeyhq/kit/src/hooks/useFormatDate';

const { formatDate } = useFormatDate();
// Will re-render when locale changes

Custom format not working

Ensure your format template uses valid date-fns tokens. Common mistake: using MM (month with leading zero for parsing) instead of LL (month with leading zero for formatting).