1k-date-formatting

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

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:

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

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).