useDateFormat

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-date-format

The module exports useDateFormat() (hook) and <DateFormatProvider> (provider). It has zero runtime dependencies — the formatter itself is supplied by you (or by a parent <DocyrusTenantProvider>).

Overview

useDateFormat() is the read side of a small provider-agnostic context. Components inside the tree call it to get { formatDate, formatDateTime, formatTime }; the provider above the tree decides how the formatting actually happens.

• No provider mounted → the hook returns a built-in sentinel that renders raw strings (String(value) for strings, .toISOString() for Date objects). Data-grid / data-table hooks detect this and skip injecting the formatter so the cell's own legacy fallback (formatDateForDisplay) still runs.
• <DocyrusTenantProvider> mounted → the provider installs formatDate / formatDateTime / formatTime backed by the tenant's dateUtils (from @docyrus/app-utils), so every cell / calendar event / side-filter chip respects the tenant's dateFormat, dateTimeFormat, longDateFormat, and timeZone settings.
• Custom provider mounted → you decide. Wrap any library (date-fns, dayjs, Luxon, Intl) with <DateFormatProvider> and components inside the tree pick it up the same way.

Usage

Consume in a component

import { useDateFormat } from '@docyrus/ui/hooks/use-date-format';

function EventRow({ startsAt }: { startsAt: string }) {
  const { formatDateTime } = useDateFormat();

  return <span>{formatDateTime(startsAt)}</span>;
}

Standard setup — let <DocyrusTenantProvider> do it

If your app already wraps its root in <DocyrusTenantProvider>, you don't have to do anything. Tenant-aware formatDate / formatDateTime / formatTime are already wired.

Custom provider (date-fns example)

import { format } from 'date-fns';
import { DateFormatProvider } from '@docyrus/ui/hooks/use-date-format';

function App({ children }) {
  return (
    <DateFormatProvider
      formatDate={v => format(new Date(v as string), 'dd/MM/yyyy')}
      formatDateTime={v => format(new Date(v as string), 'dd/MM/yyyy HH:mm')}
      formatTime={v => format(new Date(v as string), 'HH:mm')}>
      {children}
    </DateFormatProvider>
  );
}

The same pattern works with dayjs, next-intl, or any other library.

API Reference

useDateFormat()

Returns DateFormatContextValue.

<DateFormatProvider>

isDefaultDateFormatContext(ctx)

Returns true when the value returned by useDateFormat() is the built-in no-provider sentinel (raw string renderer) rather than a real provider. Internal hooks use this to avoid shadowing a cell's own fallback when no provider is mounted. Most apps don't need to call it directly.

Type Exports