---
title: Date Separator
description: Horizontal divider with centered date label
visibility: guest
draft: false
---

# Date Separator

A temporal divider for chat threads, activity feeds, and timelines. Automatically formats dates as relative labels ("Today", "Yesterday", day name) and falls back to locale-aware formatting for older dates.

## Basic Usage

:::preview{title="Today separator"}
<x-wirekit::date-separator :date="now()" />
:::

## Relative Labels

The component auto-formats based on proximity to "now":

:::preview{title="Relative date labels"}
<x-wirekit::stack gap="md">
    <x-wirekit::date-separator :date="now()" :now="now()" />
    <x-wirekit::date-separator :date="now()->subDay()" :now="now()" />
    <x-wirekit::date-separator :date="now()->subDays(3)" :now="now()" />
    <x-wirekit::date-separator :date="now()->subDays(14)" :now="now()" />
</x-wirekit::stack>
:::

## Custom Format

Override the auto-formatting with a PHP date format string:

:::preview{title="Custom format"}
<x-wirekit::date-separator :date="now()" format="d.m.Y" />
:::

## Sticky Variant

Sticks to the top of a scrollable container — ideal for chat UIs:

:::preview{title="Sticky variant"}
<x-wirekit::date-separator :date="now()" variant="sticky" />
:::

## Custom Content via Slot

Override the label entirely with your own content:

:::preview{title="Custom slot content"}
<x-wirekit::date-separator :date="now()">New messages</x-wirekit::date-separator>
:::

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `date` | `Carbon\|string` | `null` | The date to display |
| `variant` | `string` | `'inline'` | Visual variant: `inline` or `sticky` |
| `format` | `string` | `null` | PHP date format (overrides auto-formatting) |
| `now` | `Carbon\|string` | `null` | Reference date for relative labels (for testing) |
| `timezone` | `string` | `config('app.timezone')` | Timezone for date display |

## Accessibility

- `role="separator"` on root element
- `aria-label` with full human-readable date (e.g. "Monday, April 20, 2026")
- Semantic `<time>` element with `datetime` attribute (ISO format)
- Decorative border lines marked `aria-hidden="true"`

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

## Pitfalls

- **Don't use date-separator for non-date headings.** It carries an implicit `<time>` semantic — use `<x-wirekit::heading>` for plain section labels.

## Design Tokens

| Token | Used for |
| --- | --- |
| `--font-wk-sans` | Date-separator font family |
| `--font-wk-heading-weight` | Date label weight |
| `--text-wk-xs` | Date label font size |
| `--color-wk-text-muted` | Date label text |
| `--color-wk-border` | Horizontal divider line |

## Usage & Conventions

> **Prop conventions** — this component uses one or more of the shared semantic prop names (`intent` / `variant` / `tone` / `surface`). See [Prop naming conventions](/extending/prop-naming-conventions) for the canonical vocabulary, alias matrix, and decision tree.