# Time overlap

> Find a meeting time across time zones: each person’s day in hairline marks, a band you drag across everyone, and it settles into the hours you all share.

Scheduling across time zones usually means a table of clocks or a list of offsets you add up in your head. Time overlap lays one day out in your time and gives each person a strip of hairline marks, lit in their colour while they’re at work and faint while they’re not. Where everyone is at work at once, a green line runs along the ruler above the strips. A glass band the length of the meeting crosses every strip: drag it and each person’s local time ticks beside their row as it moves. Let go within an hour and a half of the overlap and the band glides into it and settles, carrying the speed you threw it with; anywhere else it lands on the nearest quarter hour. The header shows the time in yours and says whether everyone is in hours or who isn’t, and anyone outside their hours turns amber.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/time-overlap.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/time-overlap
- Registry item (source): https://hairlineui.com/r/time-overlap.json

## Usage

```tsx
import { TimeOverlap } from "@/components/time-overlap";

<TimeOverlap
  people={[
    { id: "mira", name: "Mira", timeZone: "Europe/Lisbon" },
    { id: "daniel", name: "Daniel", timeZone: "America/New_York", hours: [8, 17] },
  ]}
  onValueChange={(start) => console.log(start)}
/>
```

## Before sending an invite

Take the guests’ zones from your users table and send the time they agree on.

```tsx
"use client";
import * as React from "react";
import { TimeOverlap, type OverlapPerson } from "@/components/time-overlap";

export function InviteTime({ guests, onPick }: { guests: OverlapPerson[]; onPick: (start: Date) => void }) {
  const [start, setStart] = React.useState<Date>();
  return (
    <div className="space-y-3">
      <TimeOverlap title="Kick-off" people={guests} duration={45} value={start} onValueChange={setStart} />
      <button disabled={!start} onClick={() => start && onPick(start)}>Send invite</button>
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `people` | `OverlapPerson[]` | – | { id, name, timeZone, hours? ([start, end) in their own hours, default [9, 17]; an end before the start runs overnight), color? }. |
| `value / defaultValue` | `Date \| number` | – | The meeting’s start; without either it starts at the beginning of the first overlap. |
| `onValueChange` | `(start: Date) => void` | – | Called when the band comes to rest somewhere new. |
| `duration` | `number` | `60` | Minutes; the band’s length. |
| `day` | `Date \| number` | `today` | The day shown. |
| `timeZone` | `string` | `the visitor’s` | The zone the day is laid out in and the header’s time is given in. |
| `title` | `string` | `"Find a time"` | Over the time. |
| `locales` | `string \| string[]` | – | How times are written; the visitor’s once hydrated. |

## States

- **strips**: One row per person: name and city, a strip of 48 half-hour marks laid out in your day (lit in their colour while at work, shorter and faint otherwise), and their local time at the meeting.
- **overlap**: A 3px green line on the ruler wherever everyone is at work; the label beside it gives its length (“1 h 30 min overlap”).
- **drag**: The band follows the pointer by transform, giving a little past either end of the day. Each person’s time and the header change once per quarter hour.
- **settle**: On release the band carries its speed (a 120ms projection) and springs into the overlap if it lands within 90 minutes of it, otherwise to the nearest quarter hour.
- **status**: “Everyone’s in hours” in green with a green edge on the band, or “Daniel is outside hours” in amber, with his time in amber; the line morphs between them.
- **click**: Pressing a strip away from the band brings the band there.
- **reduced motion**: The band jumps to where it settles.

## What it handles

Time zone pickers show a table of clocks or offsets, so finding an hour that suits everyone is arithmetic you do yourself.

- **Everyone’s day at once**: One strip per person in your time, lit while they’re at work.
- **The shared hours, marked**: A green line on the ruler where everyone is working.
- **Local times as you drag**: Each person’s time ticks beside their row as the band moves.
- **It settles where it fits**: Let go near the overlap and the band glides into it.
- **Who can’t make it**: The header says so, and their time turns amber.
- **Keyboard too**: A slider: arrows move a quarter hour, Page Up and Down an hour.

## Replaces

a time zone converter, a meeting planner, a world clock, a time slot picker, a working hours table, an availability grid

## Where it fits

- **Scheduling and booking**: Picking a slot for a call with people in other countries.
- **Team and people pages**: When a distributed team is all online at once.
- **Calendar invites**: Checking a meeting time against every guest’s working hours before sending.
- **Support and on-call**: Hand-over windows between shifts in different regions.

## Notes

- The strips are one slider (role="slider") whose value text is the time and who’s in hours. Arrows move a quarter hour, Page Up and Page Down an hour, Home and End to either end of the day.
- Times are worked out with Intl in each person’s own zone, so summer time is right on the day shown. Everything time-based waits for hydration, so server and browser render the same.
- The band moves by transform while you drag and React re-renders only when it crosses a quarter hour; the strips are drawn once per set of people.
- Default colours are your chart colours with a fifth of your text colour, so they read in themes whose chart colours are pale greys.
- Installs Text morph. With reduced motion the band jumps to where it settles.

License: MIT (https://hairlineui.com/license#components)
