A premium mail client you drop into a dashboard: folders and labels on the left, the conversation list in the
middle, the thread on the right, in three resizable panes that remember their sizes. Search highlights what it finds,
rows animate out when you archive them, every action can be undone, and the whole thing runs from the keyboard. The
Compose window floats bottom-right like Gmail's, with recipient chips, rich text, attachments and autosave. Tablets
get two panes, phones one screen at a time with swipes and a full-screen composer. It uses only shadcn/ui's theme
tokens, so it looks finished in light and dark and takes on your theme.
Built from the brief in prompt/component/mail-upgrade-prompt.md (a redesign of an admin template's Mail page),
written from scratch.
Next.js 16 (App Router), React 19, TypeScript strict, Tailwind CSS 4, shadcn/ui (Radix), react-resizable-panels,
sonner, TipTap 3, motion, zustand, cmdk, react-day-picker, lucide icons, Geist and Geist Mono.
Run it
pnpm install
pnpm dev # http://localhost:3000
pnpm build && pnpm start # production
The demo page is the mail client filling the window, with a light / system / dark switch. Press ? for the
shortcuts. The address bar follows the view (?folder=sent, ?label=social, ?id=code-review), so views can be
linked and Back works.
Use it
import { Mail } from "@/components/mail"
export default function MailPage() {
return (
<div className="h-[calc(100dvh-12rem)]">
<Mail urlState />
</div>
)
}
<Mail> fills its parent, so give the parent a height. It picks its layout from its own width, not the window's,
so it works inside any dashboard shell: three panes from 900 px, two from 640 px, one below.
| Prop | Default | What it does |
|---|
data | the demo mailbox | Your mailbox: { me, people, labels, threads } (see types.ts) |
defaultFolder | "inbox" | The folder to open first (the address bar wins when urlState is on) |
defaultThreadId | — | The conversation open at first, by thread id |
urlState | false | Mirror ?folder, ?label and ?id in the address bar |
shortcuts | true | Gmail-style single-key shortcuts |
toaster | true | Mount a sonner <Toaster />; turn off if your layout already has one |
loadingDelay | 320 | How long the list shows its skeleton on first load and folder changes (0 = never) |
storageKey | "mail" | Where pane sizes are kept in localStorage |
onSend(draft) | — | Called when a message is sent, to hand it to your backend |
onReply(thread, mode, html) | — | Called when a reply or forward is sent |
className | — | Classes for the root |
All state lives in one zustand store made per <Mail> (store.ts): the actions (change with Undo snapshots,
send, reply, saveDraft, addLabel, wakeSnoozed…) are pure functions over the threads, and every count is
derived from the data, never stored. Swap createMailData() for your own data loader and call your API from
onSend / onReply, or wrap store.actions to persist changes.
What's in it
- Folders Inbox, Snoozed, Drafts, Sent, Spam, Trash, Archive with live counts, and labels in the five label
colours (a collapsible section, New label with a name and a colour). The pane collapses to an icon rail with
tooltips when dragged narrow.
- List with All mail / Unread (a fixed badge), debounced search over sender, address, subject and body with the
matches highlighted, four sort orders in a radio menu, sticky date groups, an unread dot, hover quick actions
(Archive, Trash, Read/Unread, Star), a checkbox on the avatar, Shift+click ranges, a bulk bar, a right-click menu,
attachment and thread-count chips, label dots with names on hover, rows that animate out, a loading skeleton, and a
separate empty state for an empty folder, no results, nothing unread and nothing selected.
- Toolbar fitted to the folder (Inbox, Snoozed, Drafts, Sent, Spam, Trash, Archive each get their own actions),
tooltips with shortcuts, Manage labels with search, Snooze with presets and a date picker, previous / next with
"3 of 10", and a ⋮ menu with Mark as unread, Star, Archive, Spam, Trash, Print and Copy link.
- Thread with label pills, an avatar stack, the full date on hover, a sender card (photo, Copy email, New
message), earlier messages folded into one pill, foldable message cards, quoted text behind
•••, attachment cards
with a download button, and your own messages on a quieter surface.
- Reply box that opens from a one-line pill into Reply / Reply all / Forward with formatting, attachments, Mute
this thread, a "Saved" draft indicator and ⌘↵ / Ctrl+↵.
- Compose docked bottom-right (expanded, minimized, full screen), recipient chips with contact suggestions and
red invalid addresses, Cc and Bcc, TipTap rich text (bold, italic, underline, lists, links, images), attachments by
picker or drag and drop, autosave into Drafts, Discard with confirmation, Send with Undo. Opening a draft opens it
here, filled in.
- Undo on every move, archive, delete, spam, label, snooze and send, through sonner toasts.
- Keyboard: J / K, Enter / O, Esc, E, #, !, S, U, L, H, X, R, A, F, C, /, G I, G S, G D and ? for the cheat
sheet; none of them fire while you type.
- Phones: one screen at a time, the thread slides in with Back, swipe left to archive and right to mark read, long
press to select, a Compose button that opens a full-screen sheet, 40 px tap targets and 16 px text in fields so iOS
doesn't zoom.
Accessibility
Real buttons with names, a roving tab stop in the list (↑ ↓ Home End), focus rings from --ring, labelled switches
and fields, live announcements for counts, inert behind the full-screen composer, and reduced motion respected
everywhere. axe-core (WCAG 2.2 AA) reports no issues on the main screens in either theme. One detail: shadcn's
muted-foreground on muted is 4.3 : 1, just under AA, so muted text on muted or accent surfaces uses the
foreground at 60 % instead (TEXT_ON_MUTED in parts.tsx): same palette, 5 : 1.
Checks
pnpm test # Vitest: store, Undo snapshots, send/draft/reply, snooze, search, grouping, dates, parsing
pnpm lint # ESLint (Next's config, React Compiler rules)
pnpm typecheck
node scripts/e2e.mjs [url] # 108 click-through checks in Chrome (the brief's checklist, phone and tablet)
node scripts/a11y.mjs [url] # axe-core on 7 screens × light and dark
pnpm shots [url] [scene…] # screenshots in .review/ at 1440, 1024, 768 and 390 px, light and dark
Files
components/mail/
mail.tsx <Mail>: store, layouts by width, dialogs, toaster
store.ts the zustand store and its pure thread operations (Undo snapshots)
selectors.ts counts, views, search, sorting, date groups, highlights
data.ts the demo mailbox (dates relative to now)
mail-sidebar.tsx folders, labels, New label, the icon rail
mail-list.tsx header, tabs, search, sort, bulk bar, groups, skeleton, empty states
mail-list-item.tsx a row: avatar/checkbox, quick actions, chips, swipe, long press
mail-toolbar.tsx the folder-aware toolbar
thread-view.tsx the reading pane, earlier messages, draft preview, no-selection state
message-card.tsx a message, its body (paragraphs, lists, quotes) and attachments
inline-reply.tsx the reply box
compose-window.tsx the Compose window
rich-text.tsx TipTap and its toolbar (its own chunk, preloaded while idle; editor.tsx loads it)
recipient-input.tsx address chips with suggestions
label-picker.tsx Manage labels
snooze-menu.tsx Snooze presets (+ snooze-calendar.tsx, loaded when the date picker opens)
sender-card.tsx the hover card (a tap-to-open card on touch screens)
shortcuts.tsx the keyboard shortcuts and the cheat sheet
use-thread-actions.ts every action with its toast and Undo
url-state.ts the address bar sync
components/ui/ the shadcn/ui components it uses, unchanged
public/images/avatars/ the photos (CREDITS.md), public/files/ the demo attachments
scripts/ fetch-avatars, attachments, e2e, a11y, screenshots
Re-skinning
Everything is drawn from shadcn's tokens (background, foreground, muted, accent, border, ring,
primary, destructive, sidebar) plus the five label hues in parts.tsx (LABEL_STYLES). Change your theme and
the mail follows; there are no hard-coded colours in the components. Times and counts use font-mono (Geist Mono in
a default shadcn project).
Departures from the brief
- Avatars use shadcn's
Avatar (a plain <img> with explicit width and height, lazy, with the initials fallback
delayed so it never flashes) instead of next/image, so the component installs in any React project.
- Organisation senders were renamed so the product carries no third-party trademarks: "Amazon Deals" → Cartly
Deals, "LinkedIn" → ProCircle, and the spam sender is the Inheritance Claims Office as the brief asked.
- Label views list every conversation with the label outside Spam and Trash (as Gmail does), so Updates counts 5
and Promotions 2 (the archived Server Maintenance Notice and June newsletter carry those labels).
- A Snoozed folder was added so snoozed conversations have somewhere to wait; they come back to the Inbox unread.
- The star is drawn in the foreground colour, not yellow, because the palette is frozen.
- Responsive breakpoints follow the component's own width (900 / 640 px), so it behaves the same inside a dashboard.
- Closing Compose keeps what you wrote as a draft (as mail clients do); Discard deletes it after asking.
Credits
Photos: Unsplash, listed in public/images/avatars/CREDITS.md. The names, addresses and messages are invented.
Icons: lucide. UI primitives: shadcn/ui (MIT).
