Working with Date and Time in React: @wordpress/date Tutorial

Previously in this course, we covered Internationalization in React: WordPress Translation for Plugins. While that lesson focused on translating static strings, this lesson shifts our focus to dynamic data: specifically, how to correctly handle and display date and time objects within our Knowledge Base plugin using @wordpress/date.

Why avoid native JavaScript Date?

When building WordPress plugins, you might be tempted to use the native new Date() constructor. Resist this urge. Native JavaScript date objects are notoriously difficult to handle across different timezones, and they don't respect the site-specific settings configured in the WordPress dashboard (Settings > General).

The @wordpress/date package is a wrapper around moment.js (and more recently, dayjs in newer versions) that ensures your plugin behaves exactly like the rest of WordPress. It automatically pulls the site's timezone, date format, and locale settings, providing a consistent experience for both developers and users.

The @wordpress/date API

To start, ensure you have the package installed in your project: npm install @wordpress/date --save

The library provides three primary functions you will use in your admin dashboard:

1. format: Converts a date string or timestamp into a readable format.
2. date: A wrapper that uses the site's default timezone and format settings.
3. dateI18n: Similar to date, but specifically designed to output localized date strings.

Formatting Knowledge Base Timestamps

In our Knowledge Base project, our REST API returns ISO 8601 strings (e.g., 2023-10-27T10:00:00). Let’s display the "Last Updated" date in our dashboard list component.

JAVASCRIPT
import { format, dateI18n } from CE9178">'@wordpress/date';

const PostDate = ({ dateString }) => {
    // Format the date using the site's configured settings
    const formattedDate = dateI18n(CE9178">'F j, Y', dateString);

    return (
        <div className="kb-post-date">
            Updated on: {formattedDate}
        </div>
    );
};

In the example above, dateI18n takes two arguments: the format string (using PHP date format syntax, not the standard JavaScript Intl.DateTimeFormat) and the date source. Because we are using the familiar Y-m-d or F j, Y syntax, you don't have to learn a new templating language.

Hands-on Exercise: Displaying Relative Time

In your Knowledge Base dashboard, users often prefer seeing "2 hours ago" rather than an absolute date. Modify your PostDate component to show a relative time string.

1. Import moment or use the format utility to calculate the difference.
2. Update your component to accept a date prop.
3. Use the __unstableFormatRelativeTime utility (or the standard format with a custom logic if you prefer) to display the "time ago" string.

Hint: Remember that @wordpress/date functions are designed to keep your plugin UI consistent with the core WordPress experience.

Common Pitfalls

• Mixing Formats: Don't confuse PHP date formats (like Y-m-d) with JavaScript's Intl formats. WordPress expects the PHP-style tokens.
• Timezone Mismatch: Always use the date or dateI18n functions provided by the package instead of native new Date(). Native JS objects often default to the browser's local time, which may differ from the site's configured timezone.
• Missing Dependencies: If you find that your dates aren't updating when the site settings change, ensure you are not caching the date string in a local component state unnecessarily.

Recap

Handling time in WordPress isn't just about showing numbers; it's about respecting the user's context. By using @wordpress/date, you ensure that:

• Dates match the site's admin settings.
• Timezones are handled server-side to client-side correctly.
• Translations for month names and day labels are applied automatically.

As we continue to build out our admin interface, keep in mind that Working with @wordpress/components for WordPress Admin UIs is essential for wrapping these date displays in clean, accessible UI elements like Cards or List rows.

Up next: We will tackle Implementing Drag-and-Drop Sorting, where we'll use these timestamps to order our Knowledge Base entries dynamically.