Notification

A workspace alert in a tray: author, source, and a short preview.

Bell

A bell opens the tray in a Popover. NotificationCount sits on the bell and shows unread items; opening an item marks it read and the count follows.

import { useState } from "react";
import {
  Avatar,
  AvatarFallback,
  Button,
  Icon,
  Notification,
  NotificationCount,
  NotificationTray,
  NotificationTrayHeader,
  NotificationTrayList,
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@smallest-inc/ui";

const messages = [
  { id: "1", author: "Kayak", initial: "K", tone: "bg-orange-500 text-white", time: "49m", source: "IconPlugin1", title: "API timeout", description: "Our POS integration is returning 504 errors across lunch-hour traffic." },
  { id: "2", author: "Pixel Studio", initial: "P", tone: "bg-purple-500 text-white", time: "2h", source: "IconSlack", title: "Missing webhooks", description: "Events stopped triggering after yesterday's deployment." },
  { id: "3", author: "Michael Chen", initial: "M", tone: "bg-neutral-950 text-on-inverted", time: "5h", source: "IconEmail1", title: "Export failed", description: "CSV exports stay in Processing for over 20 minutes." },
  { id: "4", author: "Billing", initial: "B", tone: "bg-neutral-800 text-on-inverted", time: "1d", source: "IconEmail1", title: "Invoice ready", description: "August usage is closed. Review the invoice before the 1st." },
] as const;

export default function NotificationBell() {
  const [open, setOpen] = useState(false);
  const [read, setRead] = useState<string[]>([]);
  const unread = messages.length - read.length;

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger
        render={
          <Button
            iconOnly
            variant="transparent"
            aria-label={unread > 0 ? `Notifications, ${unread} unread` : "Notifications"}
            className="relative"
          />
        }
      >
        <Icon name="IconBell2" />
        <NotificationCount count={unread} />
      </PopoverTrigger>
      <PopoverContent align="start" sideOffset={8} className="w-[360px] gap-0 overflow-hidden p-0">
        <NotificationTray>
          <NotificationTrayHeader>Notifications</NotificationTrayHeader>
          <NotificationTrayList>
            {messages.map((message) => (
              <Notification
                key={message.id}
                avatar={
                  <Avatar size="sm">
                    <AvatarFallback className={message.tone}>{message.initial}</AvatarFallback>
                  </Avatar>
                }
                author={message.author}
                time={message.time}
                source={<Icon name={message.source} />}
                title={message.title}
                description={message.description}
                unread={!read.includes(message.id)}
                onClick={() => setRead((current) => (current.includes(message.id) ? current : [...current, message.id]))}
              />
            ))}
          </NotificationTrayList>
        </NotificationTray>
      </PopoverContent>
    </Popover>
  );
}

Status

variant="status" is for system events. It leads with a 16px icon and a date, with an optional source, then a title and a description that wraps.

import { Icon, Notification, toast } from "@smallest-inc/ui";

export default function NotificationStatus() {
  return (
    <div className="w-full max-w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-sm">
      <Notification
        variant="status"
        icon={<Icon name="IconExclamationTriangle" className="text-danger-fg" />}
        date="Aug 5"
        title="Calls are failing"
        description="20% of calls to NYL Inbound Agent failed in the last hour."
        onClick={() => toast("Opening NYL Inbound Agent")}
      />
      <Notification
        variant="status"
        icon={<Icon name="IconExclamationCircle" className="text-warning-fg" />}
        date="Aug 1"
        source={<Icon name="IconPlugin1" />}
        title="Accumulating SIP issues"
        description="SIP errors are stacking on +1 (415) 555-0132 across inbound trunks."
        onClick={() => toast("Opening SIP trunk logs")}
      />
      <Notification
        variant="status"
        icon={<Icon name="IconDollar" className="text-danger-fg" />}
        date="Jul 30"
        title="You're running low on credits"
        description="Usage is outpacing your remaining balance for this billing period."
        onClick={() => toast("Opening billing")}
      />
    </div>
  );
}

Identity

The default variant is for messages from a person or integration: a 24px avatar, the author, a relative time and an optional source icon. Title and description truncate to one line.

import { Avatar, AvatarFallback, Icon, Notification, toast } from "@smallest-inc/ui";

export default function NotificationIdentity() {
  return (
    <div className="w-full max-w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-sm">
      <Notification
        avatar={
          <Avatar size="sm">
            <AvatarFallback className="bg-orange-500 text-white">K</AvatarFallback>
          </Avatar>
        }
        author="Kayak"
        time="49m"
        source={<Icon name="IconPlugin1" />}
        title="API timeout"
        description="Our POS integration is returning 504 errors across lunch-hour traffic."
        onClick={() => toast("Opening API timeout")}
      />
      <Notification
        avatar={
          <Avatar size="sm">
            <AvatarFallback className="bg-purple-500 text-white">P</AvatarFallback>
          </Avatar>
        }
        author="Pixel Studio"
        time="2h"
        source={<Icon name="IconSlack" />}
        title="Missing webhooks"
        description="Events stopped triggering after yesterday's deployment to the staging worker."
        onClick={() => toast("Opening Missing webhooks")}
      />
    </div>
  );
}

Read

Notifications are unread by default. Set unread={false} once an item has been opened; its title drops to regular weight.

import { Avatar, AvatarFallback, Icon, Notification } from "@smallest-inc/ui";

export default function NotificationRead() {
  return (
    <div className="w-full max-w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-sm">
      <Notification
        avatar={
          <Avatar size="sm">
            <AvatarFallback className="bg-neutral-950 text-on-inverted">M</AvatarFallback>
          </Avatar>
        }
        author="Michael Chen"
        time="5h"
        source={<Icon name="IconEmail1" />}
        title="Export failed"
        description="CSV exports stay in Processing for over 20 minutes and never complete."
      />
      <Notification
        unread={false}
        avatar={
          <Avatar size="sm">
            <AvatarFallback className="bg-blue-600 text-white">V</AvatarFallback>
          </Avatar>
        }
        author="Voice Lab"
        time="2d"
        source={<Icon name="IconSlack" />}
        title="Clone finished"
        description="The new speaker clone is ready to review in Voices."
      />
    </div>
  );
}

Tray

NotificationTray caps its height at 28rem and NotificationTrayList scrolls with edge fades. The header's overflow menu holds Settings and Clear all.

Notifications

import { useState } from "react";
import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
  Icon,
  MoreHorizontalIcon,
  Notification,
  NotificationTray,
  NotificationTrayEmpty,
  NotificationTrayHeader,
  NotificationTrayList,
} from "@smallest-inc/ui";

const alerts = [
  { id: "1", icon: "IconExclamationTriangle", tone: "text-danger-fg", date: "Aug 5", title: "Calls are failing", description: "20% of calls to NYL Inbound Agent failed in the last hour." },
  { id: "2", icon: "IconExclamationCircle", tone: "text-warning-fg", date: "Aug 1", title: "Accumulating SIP issues", description: "SIP errors are stacking on +1 (415) 555-0132 across inbound trunks." },
  { id: "3", icon: "IconDollar", tone: "text-danger-fg", date: "Jul 30", title: "You're running low on credits", description: "Usage is outpacing your remaining balance for this billing period." },
  { id: "4", icon: "IconExclamationCircle", tone: "text-warning-fg", date: "Jul 28", title: "Concurrency limit reached", description: "Live calls were queued after the workspace hit its concurrent session cap." },
  { id: "5", icon: "IconExclamationTriangle", tone: "text-danger-fg", date: "Jul 24", title: "Webhook deliveries failing", description: "call.completed events to hooks.acme-insurance.com are returning 500." },
  { id: "6", icon: "IconExclamationCircle", tone: "text-warning-fg", date: "Jul 20", title: "Campaign paused", description: "Q3 renewals paused after reaching its daily call limit." },
] as const;

export default function NotificationTrayExample() {
  const [items, setItems] = useState<readonly (typeof alerts)[number][]>(alerts);
  const [read, setRead] = useState<string[]>([]);

  return (
    <div className="flex flex-col items-start gap-4">
      <div className="w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-xl">
        <NotificationTray className={items.length === 0 ? "min-h-72" : undefined}>
          <NotificationTrayHeader
            trailing={
              <DropdownMenu>
                <DropdownMenuTrigger
                  render={<Button iconOnly variant="transparent" size="xs" aria-label="Notification actions" />}
                >
                  <MoreHorizontalIcon />
                </DropdownMenuTrigger>
                <DropdownMenuContent align="end" className="w-44">
                  <DropdownMenuItem>Settings</DropdownMenuItem>
                  <DropdownMenuItem variant="danger" disabled={items.length === 0} onClick={() => setItems([])}>
                    Clear all
                  </DropdownMenuItem>
                </DropdownMenuContent>
              </DropdownMenu>
            }
          >
            Notifications
          </NotificationTrayHeader>
          {items.length === 0 ? (
            <NotificationTrayEmpty variant="caught-up" />
          ) : (
            <NotificationTrayList>
              {items.map((item) => (
                <Notification
                  key={item.id}
                  variant="status"
                  icon={<Icon name={item.icon} className={item.tone} />}
                  date={item.date}
                  title={item.title}
                  description={item.description}
                  unread={!read.includes(item.id)}
                  onClick={() => setRead((current) => [...current, item.id])}
                />
              ))}
            </NotificationTrayList>
          )}
        </NotificationTray>
      </div>
      {items.length === 0 ? (
        <Button
          variant="secondary"
          size="sm"
          onClick={() => {
            setItems(alerts);
            setRead([]);
          }}
        >
          Restore notifications
        </Button>
      ) : null}
    </div>
  );
}

Empty

variant="never" is for a workspace that has never received a notification. variant="caught-up", the default, is for a tray that has been cleared.

Notifications

No notifications yet

Alerts about your workspace will show up here.

Notifications

You're all caught up

import {
  NotificationTray,
  NotificationTrayEmpty,
  NotificationTrayHeader,
} from "@smallest-inc/ui";

export default function NotificationEmpty() {
  return (
    <div className="flex w-full flex-wrap gap-4">
      <div className="w-full max-w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-xl">
        <NotificationTray className="min-h-72">
          <NotificationTrayHeader>Notifications</NotificationTrayHeader>
          <NotificationTrayEmpty variant="never" />
        </NotificationTray>
      </div>
      <div className="w-full max-w-[360px] overflow-hidden rounded-[16px] bg-neutral-0 shadow-xl">
        <NotificationTray className="min-h-72">
          <NotificationTrayHeader>Notifications</NotificationTrayHeader>
          <NotificationTrayEmpty variant="caught-up" />
        </NotificationTray>
      </div>
    </div>
  );
}

Count

Counts above 99 show 99+. Wider counts sit farther right so they nick the bell's corner instead of covering it. At zero the count scales out.

import { useState } from "react";
import { Button, Icon, NotificationCount } from "@smallest-inc/ui";

const counts = [1, 12, 100];

export default function NotificationCountExample() {
  const [read, setRead] = useState(false);

  return (
    <div className="flex items-center gap-8">
      {counts.map((count) => {
        const unread = read ? 0 : count;
        return (
          <Button
            key={count}
            iconOnly
            variant="transparent"
            aria-label={unread > 0 ? `Notifications, ${unread > 99 ? "99+" : unread} unread` : "Notifications"}
            className="relative"
          >
            <Icon name="IconBell2" />
            <NotificationCount count={unread} />
          </Button>
        );
      })}
      <Button variant="secondary" size="sm" onClick={() => setRead((current) => !current)}>
        {read ? "Restore unread" : "Mark all read"}
      </Button>
    </div>
  );
}

Best practices

When to use

Use for workspace alerts people review later: failing calls, SIP errors, credits, webhooks, messages from integrations.
Use Toast for a brief confirmation of an action that just happened, and Dialog when a decision is required now.

Behavior

Open the tray from a bell in a Popover. NotificationCount shows unread items, caps at 99+, and scales out at zero. Wider counts sit farther right so they nick the bell's corner.
Use variant="status" for system events (icon + date + wrapping description). Use the default identity variant for messages from a person or integration (avatar + author + relative time + optional source).
Opening an item marks it read: set unread={false} and its title drops to regular weight.
NotificationTray caps at 28rem; NotificationTrayList scrolls with edge fades. The header's overflow holds Settings and Clear all, and Clear all is disabled when the tray is empty.

Content

Status titles state the problem ("Calls are failing"); descriptions give the scope ("20% of calls to NYL Inbound Agent failed in the last hour.").
Use NotificationTrayEmpty variant="never" ("No notifications yet") for a new workspace and variant="caught-up" ("You're all caught up") after clearing.

Accessibility

Name the bell with the unread count ("Notifications, 3 unread"); NotificationCount is aria-hidden. Name the overflow control ("Notification actions").

PreviousMulti Select NextPills