DateSeparator

DateSeparator marks where a day starts in a message list. The lists render it from the DateSeparator override key: before the first message, between messages sent on different days, before the first message that arrived since the user last read the channel, and floating at the top while the list scrolls, once that day's separator has scrolled out of view. Separators explains when each one shows.

Date separators are on in MessageList and off in VirtualizedMessageList. The withDateSeparator prop of either list turns them on or off.

Best practices

To change only the date's format, change the timestamp.DateSeparator key or pass format props, rather than replacing the component. Date and time formatting shows both.
Keep a replacement light: the list renders one per day it shows.
Pass floating on to the default, or style it yourself: the floating separator gets its position from the str-chat__date-separator--floating class.
In a replacement that renders its own markup, keep the str-chat__date-separator class, add data-date={date.toISOString()}, and add str-chat__date-separator--floating when floating is true. The lists find the inline separators by that class, ignoring the one with the --floating class, and read their dates from data-date to decide when the floating separator shows. A replacement that wraps the default, as in UI customization, keeps all three.

Basic usage

This list shows no date separators:

import { MessageList } from "stream-chat-react";

export const MessagesWithoutDates = () => (
  <MessageList withDateSeparator={false} />
);

DateSeparator also works on its own, for a list of your own:

import { DateSeparator } from "stream-chat-react";

export const DayHeader = ({ date }: { date: Date }) => (
  <DateSeparator date={date} />
);

UI customization

This replacement keeps the default and writes the full date:

import type { DateSeparatorProps } from "stream-chat-react";
import { DateSeparator, WithComponents } from "stream-chat-react";

const formatFullDate = (date: Date) =>
  date.toLocaleDateString(undefined, { dateStyle: "full" });

const FullDateSeparator = (props: DateSeparatorProps) => (
  <DateSeparator {...props} formatDate={formatFullDate} />
);

const overrides = { DateSeparator: FullDateSeparator };

export const App = () => (
  <WithComponents overrides={overrides}>
    {/* the rest of the app */}
  </WithComponents>
);

The override reaches the separators in both lists, the floating one, and the one above a thread's parent message.

Props

Prop	Type	Default	Description
`date`	`Date`	required	The date to show.
`calendar`	`boolean \| null`	from `timestamp.DateSeparator`	Writes the date relative to today, such as "Yesterday".
`calendarFormats`	`Record<string, string> \| string`	from `timestamp.DateSeparator`	The calendar's formats, used with `calendar`.
`className`	`string`		Added to the `str-chat__date-separator` class.
`floating`	`boolean`	`false`	Adds the `str-chat__date-separator--floating` class. The lists set it on the separator that floats at the top.
`format`	`string`	from `timestamp.DateSeparator`	A Day.js format, such as `dddd L`. Ignored while `calendar` is on.
`formatDate`	`(date: Date) => string`		Writes the date, and wins over every other option. `<MessageList/>` passes its `formatDate` to the separators between messages, and both lists pass theirs to the one above a thread's parent message. The floating separator and those between messages in `<VirtualizedMessageList/>` don't get it.
`position`	`'left' \| 'center' \| 'right'`		Not used by the default separator.
`relativeCompact`	`boolean`		Writes a short relative date, such as "3d ago". See Relative compact dates.
`relativeCompactMaxDays`	`number`	`6`	The most days ago still written as days.
`relativeCompactMaxWeeks`	`number`	`3`	The most weeks ago still written as weeks.
`relativeCompactWeekRounding`	`'ceil' \| 'floor'`	`'floor'`	How weeks are counted.
`unread`	`boolean`		Set by the lists on the separator before the first new message. The default separator looks the same either way.

The default writes "Today", "Yesterday" or "Last Monday", then a date such as "Tue, 3 Sep". A prop wins over the same option in the key's expression.