name: 1k-date-formatting
description: Guides proper date and time formatting in OneKey app. Use when displaying dates/times in UI, formatting timestamps, or when dates need to follow app locale settings. Date, time, locale, formatDate, dateUtils.

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