Inbox

Install

pnpm dlx shadcn@latest add @vegastack/inbox

Usage

import {
  Inbox,
  InboxEmphasis,
  InboxFilters,
  InboxGroup,
  InboxItem,
  InboxMarkAllRead,
} from "@/components/ui/inbox";

<Inbox
  onClose={close}
  actions={<InboxMarkAllRead onClick={markAllRead} />}
  filters={
    <InboxFilters value={view} onValueChange={setView} unreadCount={3} />
  }
  onLoadMore={loadOlder}
  hasMore={hasMore}
  loadingMore={loadingOlder}
>
  <InboxGroup label="Today">
    <InboxItem
      unread
      avatar={{ name: "Asha Kumar" }}
      title={
        <>
          <InboxEmphasis>Asha</InboxEmphasis> assigned you{" "}
          <InboxEmphasis>Send Skyline delivery schedule</InboxEmphasis>
        </>
      }
      meta="Skyline Tower B · Project"
      time={createdAt}
      href="/tasks/41"
      onToggleRead={toggleRead}
    />
  </InboxGroup>
</Inbox>;

When to use

• Use it for the notifications panel: a feed of person events (someone assigned, mentioned or asked you) and system events (a meeting processed, an export finished, a job failed) that the user reads, acts on and marks read.
• Inbox fills its container. Dock it in a Sheet, a Popover or a panel beside the sidebar; on a phone give that container the whole screen.
• Don't use it for transient confirmations (Toast), a record's history (Timeline), or a bare unread count in the chrome (NotificationBell).

Anatomy

• Inbox — the frame: title, header actions (InboxMarkAllRead, InboxMenuAction, any InboxHeaderAction), the ✕ when onClose is set, the filters row, a scrolling body and a footer — or, with onLoadMore, the infinite-scroll end.
• InboxFilters — the All | Unread chips, with the count on Unread.
• InboxGroup — a label that sticks within the scroll area, with no divider above or below it (16px above, except on the first group; 6px below), over a list it names. InboxList is the ungrouped list.
• InboxItem — one row. Title 14px regular — foreground when unread, muted once read — with the actor and record (InboxEmphasis) in medium; the tint marks unread. Meta 12px muted (the ramp has no 13px step), time 12px muted; 16px sides and 12px vertical padding; a 1px divider between rows only, and a tint, reaching both edges. The ⋯ menu sizes to its content (224–320px).
• InboxEmpty, InboxSkeleton, InboxError — the empty, first-load and failed-load states.

Examples

Person, system, actionable and grouped events

A person event leads with the actor's 28px avatar; a system event leads with its icon in a muted 28px tile (destructive for a failure). Emphasise the actor and the record with InboxEmphasis so identical events name their record. actions adds up to three chips (the first can be primary), each with loading and done states. count marks a row standing for grouped repeats ("Raj assigned you 3 tasks"). Unread rows carry a soft tint and a foreground title; read titles are muted. A fixed right column keeps the time on top; hover a row, or tab into it, to show Mark read / Mark unread and the ⋯ menu below it.

Infinite scroll

Pass onLoadMore, hasMore and loadingMore: a sentinel under the last row calls onLoadMore as it nears the viewport (page 15 rows at a time). While a page loads, three skeleton rows stand in — no spinner. Set loadMoreError after a failure to show a ghost Try again, and hasMore={false} ends the list on "You’re all caught up".

Empty

Loading

API Reference

InboxFilters

InboxGroup

InboxItem

InboxEmpty

InboxError

InboxSkeleton

Accessibility

• Each group is a list named by its label; the whole row is one link (href, or your router link through linkRender), and the chips and hover controls sit above it.
• The hover controls are always in the tab order and show on focus-within; on touch screens they are always visible.
• An unread row carries a soft tint and an sr-only "Unread:" before its title.
• The header icon buttons are named by their tooltips.

Do / Don't