Date - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatDate",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatDate } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A composable date/time display component that formats Unix timestamps based on temporal proximity — today, yesterday, last week, or older.",
  "cssRootClass": ".cometchat-date",
  "subComponents": ["Root", "Text"],
  "props": {
    "Root": {
      "timestamp": { "type": "number", "default": "undefined", "note": "Required. Unix timestamp in seconds." },
      "formatConfig": { "type": "CometChatDateFormatConfig", "default": "{ today: 'hh:mm A', yesterday: 'Yesterday', lastWeek: 'dddd', otherDays: 'DD/MM/YYYY' }" },
      "formatter": { "type": "(timestamp: number) => string", "default": "undefined" },
      "variant": { "type": "'caption' | 'caption2' | 'body' | 'label' | 'separator'", "default": "'caption'" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Text": {
      "className": { "type": "string", "default": "undefined" }
    }
  },
  "types": {
    "CometChatDateFormatConfig": {
      "today": "string | undefined",
      "yesterday": "string | undefined",
      "lastWeek": "string | undefined",
      "otherDays": "string | undefined",
      "relativeTime": "{ minute?: string; minutes?: string; hour?: string; hours?: string } | undefined"
    },
    "CometChatDateVariant": "'caption' | 'caption2' | 'body' | 'label' | 'separator'",
    "CometChatDateContextValue": {
      "timestamp": "number",
      "formattedDate": "string",
      "isoDate": "string",
      "fullDateLabel": "string",
      "variant": "CometChatDateVariant"
    }
  }
}

Where It Fits

CometChatDate is a base component used wherever a formatted date or time needs to be displayed. It appears in conversation list trailing dates, message list date separators, sticky date headers, message information receipts, thread headers, call logs, and search results. It renders a semantic <time> element with a datetime attribute for accessibility and SEO.

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function ConversationRow({ name, lastMessageTimestamp }) {
  return (
    <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
      <span>{name}</span>
      <CometChatDate.Root
        timestamp={lastMessageTimestamp}
        formatConfig={{
          today: "hh:mm A",
          yesterday: "Yesterday",
          lastWeek: "dddd",
          otherDays: "DD/MM/YYYY",
          relativeTime: { minute: "1 min", minutes: "%d mins", hour: "1 hr", hours: "%d hrs" },
        }}
      >
        <CometChatDate.Text />
      </CometChatDate.Root>
    </div>
  );
}

Minimal Render

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function Demo() {
  return (
    <CometChatDate.Root timestamp={Math.floor(Date.now() / 1000)}>
      <CometChatDate.Text />
    </CometChatDate.Root>
  );
}

Root CSS class: .cometchat-date

Sub-Components

CometChatDate is a compound component with two sub-components:

Sub-component	Purpose
`Root`	Wraps content in a `<time>` element, provides context (timestamp, formatted date, variant) to children. Sets `datetime`, `aria-label`, and `title` attributes.
`Text`	Renders the formatted date string from context.

Root

The outermost wrapper. Renders a semantic <time> element with datetime (ISO 8601), aria-label (full human-readable date), and title (hover tooltip). Provides context to child sub-components. If no children are provided, renders the formatted date text directly.

<CometChatDate.Root timestamp={message.getSentAt()} variant="caption">
  <CometChatDate.Text />
</CometChatDate.Root>

Text

Reads the formatted date string from context and renders it in a <span>. Must be used inside CometChatDate.Root.

<CometChatDate.Root timestamp={message.getSentAt()}>
  <CometChatDate.Text />
</CometChatDate.Root>

Common Patterns

Conversation list trailing date

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function TrailingDate({ timestamp }) {
  return (
    <CometChatDate.Root
      timestamp={timestamp}
      formatConfig={{
        today: "hh:mm A",
        yesterday: "Yesterday",
        lastWeek: "dddd",
        otherDays: "DD/MM/YYYY",
        relativeTime: { minute: "1 min", minutes: "%d mins", hour: "1 hr", hours: "%d hrs" },
      }}
    >
      <CometChatDate.Text />
    </CometChatDate.Root>
  );
}

Message list date separator

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function DateSeparator({ timestamp }) {
  return (
    <CometChatDate.Root
      timestamp={timestamp}
      variant="label"
      formatConfig={{
        today: "Today",
        yesterday: "Yesterday",
        lastWeek: "dddd, DD MMM",
        otherDays: "DD MMM, YYYY",
      }}
    >
      <CometChatDate.Text />
    </CometChatDate.Root>
  );
}

Message info receipt date

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function ReceiptDate({ timestamp }) {
  return (
    <CometChatDate.Root
      timestamp={timestamp}
      formatConfig={{
        today: "hh:mm A",
        yesterday: "DD MMM, hh:mm A",
        otherDays: "DD MMM, hh:mm A",
      }}
    >
      <CometChatDate.Text />
    </CometChatDate.Root>
  );
}

Custom formatter function

Use the formatter prop for full control over date formatting, for example with Intl.DateTimeFormat or a library like date-fns.

import { CometChatDate } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function CustomDate({ timestamp }) {
  return (
    <CometChatDate.Root
      timestamp={timestamp}
      formatter={(ts) =>
        new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeStyle: "short" }).format(ts * 1000)
      }
    >
      <CometChatDate.Text />
    </CometChatDate.Root>
  );
}

Using the hook independently

The useCometChatDate hook can be used outside the component for custom date rendering.

import { useCometChatDate } from "@cometchat/chat-uikit-react";

function CustomDateDisplay({ timestamp }) {
  const { formattedDate, isoDate, fullDateLabel } = useCometChatDate({
    timestamp,
    formatConfig: { today: "hh:mm A", yesterday: "Yesterday", otherDays: "DD/MM/YYYY" },
  });

  return (
    <time dateTime={isoDate} aria-label={fullDateLabel}>
      Sent: {formattedDate}
    </time>
  );
}

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-date) consumes these tokens via var().
Overrides target .cometchat-date descendant selectors.

Key Selectors

Target	Selector
Root	`.cometchat-date`
Text	`.cometchat-date__text`
Caption variant	`.cometchat-date[data-variant="caption"]`
Body variant	`.cometchat-date[data-variant="body"]`
Label variant	`.cometchat-date[data-variant="label"]`

Example: Brand-themed date

App.css

.cometchat-date {
  color: var(--brand-muted, #888);
}

.cometchat-date[data-variant="label"] {
  color: var(--brand-primary, #6851ff);
  font-weight: 600;
}

Customization Matrix

What to change	Where	Property/API	Example
Date format	Component props	`formatConfig` on `Root`	`<Root formatConfig={{ today: "h:mm A" }}>`
Full custom format	Component props	`formatter` on `Root`	`<Root formatter={(ts) => ...}>`
Typography variant	Component props	`variant` on `Root`	`<Root variant="label">`
Text color	Global CSS	`.cometchat-date`	`color: #888;`
Font	Global CSS	`.cometchat-date[data-variant]`	`font: 500 12px Inter;`
Padding	Global CSS	`.cometchat-date`	`padding: 4px 8px;`

Props

All props are optional unless noted otherwise.

CometChatDate.Root

timestamp

Unix timestamp in seconds of the date to display.


Type	`number`
Default	`undefined`

Required.

formatConfig

Configuration object controlling the display format based on temporal proximity. Each field is a format pattern string. Supported tokens: DD, D, MMMM, MMM, MM, M, YYYY, YY, hh, h, mm, m, A, dddd, ddd, dd. Use %d in relativeTime fields as a count placeholder.


Type	`CometChatDateFormatConfig`
Default	`{ today: 'hh:mm A', yesterday: 'Yesterday', lastWeek: 'dddd', otherDays: 'DD/MM/YYYY' }`

interface CometChatDateFormatConfig {
  today?: string;
  yesterday?: string;
  lastWeek?: string;
  otherDays?: string;
  relativeTime?: {
    minute?: string;
    minutes?: string;
    hour?: string;
    hours?: string;
  };
}

formatter

Custom formatter function. When provided, overrides formatConfig. Receives the Unix timestamp (seconds) and returns the display string.


Type	`(timestamp: number) => string`
Default	`undefined`

variant

Controls the typography style. caption for inline dates (conversation trailing), caption2 for smaller inline dates, body for larger contexts, label for date separators (message list), separator for full-width separators.


Type	`'caption' \| 'caption2' \| 'body' \| 'label' \| 'separator'`
Default	`'caption'`

className

Custom CSS class appended to the <time> root element.


Type	`string`
Default	`undefined`

children

Sub-components to render inside the <time> element. If omitted, renders the formatted date text directly.


Type	`ReactNode`
Default	`undefined`

CometChatDate.Text

className

Custom CSS class appended to the text <span> element.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-date`
Root (caption)	`.cometchat-date[data-variant="caption"]`
Root (body)	`.cometchat-date[data-variant="body"]`
Root (label)	`.cometchat-date[data-variant="label"]`
Text	`.cometchat-date__text`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​Text

​Common Patterns

​Conversation list trailing date

​Message list date separator

​Message info receipt date

​Custom formatter function

​Using the hook independently

​CSS Architecture

​Key Selectors

​Example: Brand-themed date

​Customization Matrix

​Props

​CometChatDate.Root

​timestamp

​formatConfig

​formatter

​variant

​className

​children

​CometChatDate.Text

​className

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

Text

Common Patterns

Conversation list trailing date

Message list date separator

Message info receipt date

Custom formatter function

Using the hook independently

CSS Architecture

Key Selectors

Example: Brand-themed date

Customization Matrix

Props

CometChatDate.Root

timestamp

formatConfig

formatter

variant

className

children

CometChatDate.Text

className

CSS Selectors