DateField

DateField

The <DateField> component displays date and time values with customizable formatting. It supports localization and timezone handling.

Usage

Display dates in lists and show pages:

import { DataTable, DateField } from '@/components/admin';

const PostList = () => (
  <DataTable>
    <DataTable.Col source="title" />
    <DataTable.Col source="published_at">
      <DateField />
    </DataTable.Col>
    <DataTable.Col source="updated_at">
      <DateField showTime />
    </DataTable.Col>
  </DataTable>
);

Installation

Terminal
npx better-admin add date-field

Props

PropRequiredTypeDefaultDescription
sourceOptional*stringFrom colField name to display
recordOptionalobjectFrom contextRecord object
showTimeOptionalbooleanfalseShow time along with date
showDateOptionalbooleantrueShow date
localesOptionalstring | string[]browserLocale for formatting
optionsOptionalIntl.DateTimeFormatOptions-Date format options
emptyTextOptionalstring"-"Text when value is empty

*source is required unless provided by DataTable.Col

Show Time

Display date and time together:

<DateField source="created_at" showTime />
<DateField source="last_login" showTime />

Time Only

Display only the time:

<DateField source="scheduled_at" showDate={false} showTime />

Custom Format

Use Intl.DateTimeFormatOptions for custom formatting:

<DateField 
  source="published_at"
  options={{
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  }}
/>
{/* Output: January 15, 2024 */}

<DateField 
  source="created_at"
  options={{
    dateStyle: 'short'
  }}
/>
{/* Output: 1/15/24 */}

<DateField 
  source="updated_at"
  options={{
    dateStyle: 'medium',
    timeStyle: 'short'
  }}
  showTime
/>
{/* Output: Jan 15, 2024, 2:30 PM */}

Localization

Display dates in different locales:

<DateField source="published_at" locales="en-US" />
<DateField source="published_at" locales="fr-FR" />
<DateField source="published_at" locales="de-DE" />
<DateField source="published_at" locales={['en-US', 'en-GB']} />

In Show Pages

Use DateField in show layouts:

import { Show, SimpleShowLayout, TextField, DateField } from '@/components/admin';

export const PostShow = () => (
  <Show>
    <SimpleShowLayout>
      <TextField source="title" />
      <DateField source="published_at" showTime />
      <DateField source="created_at" showTime />
      <DateField source="updated_at" showTime />
    </SimpleShowLayout>
  </Show>
);

With better-query

DateField automatically works with better-query dates:

import { useQuery } from 'better-admin';
import { DataTable, DateField, TextField } from '@/components/admin';
import { query } from '@/lib/query';

export function PostList() {
  const { data } = useQuery("post", query);

  return (
    <DataTable data={data}>
      <DataTable.Col source="title">
        <TextField />
      </DataTable.Col>
      <DataTable.Col source="published_at">
        <DateField showTime />
      </DataTable.Col>
      <DataTable.Col source="updated_at">
        <DateField 
          options={{ dateStyle: 'short', timeStyle: 'short' }}
          showTime
        />
      </DataTable.Col>
    </DataTable>
  );
}

Empty Values

Customize text for empty/null dates:

<DateField source="completed_at" emptyText="Not completed" />
<DateField source="deleted_at" emptyText="Active" />

Relative Time

Create a custom relative time field:

import { useRecordContext } from '@/lib/hooks';
import { formatDistanceToNow } from 'date-fns';

export function RelativeDateField({ source }: { source: string }) {
  const record = useRecordContext();
  const date = record?.[source];
  
  if (!date) return <span>-</span>;
  
  return (
    <span className="text-muted-foreground">
      {formatDistanceToNow(new Date(date), { addSuffix: true })}
    </span>
  );
}

// Usage
<DataTable.Col source="created_at">
  <RelativeDateField />
</DataTable.Col>

With Tooltips

Show detailed date on hover:

import { DateField } from '@/components/admin';
import { Tooltip } from '@/components/ui/tooltip';
import { useRecordContext } from '@/lib/hooks';

export function DateFieldWithTooltip({ source }: { source: string }) {
  const record = useRecordContext();
  const date = record?.[source];
  
  if (!date) return <span>-</span>;
  
  return (
    <Tooltip content={new Date(date).toLocaleString()}>
      <span>
        <DateField source={source} options={{ dateStyle: 'short' }} />
      </span>
    </Tooltip>
  );
}

Complete Example

import {
  DataTable,
  TextField,
  DateField,
  NumberField,
  ReferenceField,
  EditButton,
} from '@/components/admin';

export const OrderList = () => (
  <DataTable>
    <DataTable.Col source="order_number">
      <TextField />
    </DataTable.Col>
    
    <DataTable.Col label="Customer">
      <ReferenceField source="customer_id" reference="customers">
        <TextField source="name" />
      </ReferenceField>
    </DataTable.Col>
    
    <DataTable.Col source="total">
      <NumberField options={{ style: 'currency', currency: 'USD' }} />
    </DataTable.Col>
    
    <DataTable.Col source="ordered_at">
      <DateField 
        showTime
        options={{
          dateStyle: 'medium',
          timeStyle: 'short'
        }}
      />
    </DataTable.Col>
    
    <DataTable.Col source="shipped_at">
      <DateField 
        emptyText="Not shipped"
        options={{ dateStyle: 'short' }}
      />
    </DataTable.Col>
    
    <DataTable.Col source="delivered_at">
      <DateField 
        emptyText="In transit"
        options={{ dateStyle: 'short' }}
      />
    </DataTable.Col>
    
    <DataTable.Col label="Actions">
      <EditButton />
    </DataTable.Col>
  </DataTable>
);

Date Format Presets

Common format examples:

{/* Short date: 1/15/24 */}
<DateField source="date" options={{ dateStyle: 'short' }} />

{/* Medium date: Jan 15, 2024 */}
<DateField source="date" options={{ dateStyle: 'medium' }} />

{/* Long date: January 15, 2024 */}
<DateField source="date" options={{ dateStyle: 'long' }} />

{/* Full date: Monday, January 15, 2024 */}
<DateField source="date" options={{ dateStyle: 'full' }} />

{/* Date and time: 1/15/24, 2:30 PM */}
<DateField 
  source="datetime" 
  showTime
  options={{ 
    dateStyle: 'short',
    timeStyle: 'short'
  }} 
/>

{/* Custom: Jan 15 at 2:30 PM */}
<DateField 
  source="datetime"
  showTime
  options={{
    month: 'short',
    day: 'numeric',
    hour: 'numeric',
    minute: '2-digit',
    hour12: true
  }}
/>

Timezone Handling

Handle timezones:

<DateField 
  source="scheduled_at"
  showTime
  options={{
    timeZone: 'America/New_York',
    timeZoneName: 'short'
  }}
/>

Next Steps

Edit on GitHub

On this page