# 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](https://getstream.io/chat/docs/sdk/react/ui/components/message-list-ui/#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](https://getstream.io/chat/docs/sdk/react/features/app-experience/localization/#component-props) 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](#ui-customization), keeps all three.

## Basic usage

This list shows no date separators:

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

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

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

```tsx
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:

```tsx
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](https://getstream.io/chat/docs/sdk/react/features/app-experience/localization/#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.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/component-reference/message/dateseparator/](https://getstream.io/chat/docs/sdk/react/component-reference/message/dateseparator/).