# DateSeparator

> **Info:** This is release candidate documentation for **Stream Chat React SDK v15**. For the latest stable version, see the [latest version (v14)](https://getstream.io/chat/docs/sdk/react/).

`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 user scrolls. [Separators](https://getstream.io/chat/docs/sdk/react/v15/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/v15/ui/customizing/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.

## 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 and the floating one. It doesn't reach the separator above a thread's parent message, which the thread renders with the SDK's own `DateSeparator`; change that one through the `timestamp.DateSeparator` key.

## 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 own `formatDate` to the separators between messages; the floating separator and those of `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/v15/ui/customizing/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/v15/component-reference/message/dateseparator/](https://getstream.io/chat/docs/sdk/react/v15/component-reference/message/dateseparator/).