DesktopNotification

Code

import { DesktopNotification } from "@fadymondy/nasaq/web";export const Preview = () => (  <DesktopNotification    platform="windows"    appName="Nasaq"    title="Deploy finished"    body="Production is on v1.4.2."    actions={[{ id: "open", label: "Open" }]}    onAction={(id) => console.log(id)}    onClose={() => {}}  />);

Alerts & Notifications · beta

Live examples and controls: DesktopNotification in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/desktop-notification.json

A card that looks like the notification your operating system shows. Use it in an Electron app's settings screen ("this is what alerts look like"), in an onboarding tour, or in a web preview of a desktop app. It draws the card. It does not raise a real system notification: for that call new Notification() in the renderer or Notification in the Electron main process. NotificationPermissionPrompt and useNotificationPermission handle the permission part.

When to useCopy Anchor Link

• Previewing or documenting what a desktop alert will look like.
• Asking for notification permission politely before the system dialog.

When not to useCopy Anchor Link

• Alerts inside the page: use Toast.
• A history of past alerts: use NotificationCenter.

ImportCopy Anchor Link

import { DesktopNotification } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { DesktopNotification } from "@fadymondy/nasaq/web";

export const Preview = () => (
  <DesktopNotification
    platform="windows"
    appName="Nasaq"
    title="Deploy finished"
    body="Production is on v1.4.2."
    actions={[{ id: "open", label: "Open" }]}
    onAction={(id) => console.log(id)}
    onClose={() => {}}
  />
);

AnatomyCopy Anchor Link

DesktopNotification              data-slot="desktop-notification" (data-platform), role="alert"
├─ app tile                      your icon, or the first letter of appName
├─ text button                   title and body (macOS: title first. Windows: app name, then title)
├─ time                          "now" or a localised time
├─ close                         macOS: on hover or focus, at the leading corner. Windows: always, with an options button
├─ image                         optional picture
└─ actions                       secondary buttons

DesktopNotificationStack         corner, top on macOS and bottom on Windows, inline-end side
NotificationPermissionPrompt     data-slot="desktop-notification-permission" (data-step)

APICopy Anchor Link

DesktopNotification: every div prop except title, children and onClick, plus:

DesktopNotificationStack: items: DesktopNotificationEntry[] (each has an id plus card props), platform, onClose(id), onAction(id, action), onActivate(id), max (3), placement ("absolute" or "fixed").

NotificationPermissionPrompt: permission ("default" | "granted" | "denied" | "unsupported"), onRequest, onDismiss, onTest, onOpenSettings, labels.

useNotificationPermission(): { permission, request }, reading Notification.permission. permissionStep(permission, asking) is the pure step function.

ExamplesCopy Anchor Link

Ask first, then send

import { NotificationPermissionPrompt, useNotificationPermission } from "@fadymondy/nasaq/web";

export function EnableAlerts() {
  const { permission, request } = useNotificationPermission();
  return (
    <NotificationPermissionPrompt
      permission={permission}
      onRequest={request}
      onTest={() => new Notification("Nasaq", { body: "It works." })}
    />
  );
}

AccessibilityCopy Anchor Link

• Each card is role="alert", so a new one is announced. Buttons have names, and the close button is reachable by keyboard even when it is hidden until hover.
• dismissAfter pauses on hover and on focus, so a keyboard user is not raced. Do not use it for alerts that need an answer.
• The permission steps are announced through a polite live region. State is text, never only an icon.

RTL & i18nCopy Anchor Link

• English and Arabic follow the Nasaq locale. The stack sits on the left in Arabic and the macOS close button moves to the right corner. Titles and bodies use dir="auto".
• No operating system logos are drawn, on purpose. The tile is your app icon.

Styling & tokensCopy Anchor Link

• Uses bg-popover, bg-card, border-border, shadow-floating. The macOS blur needs the card to sit over something.
• Target [data-slot="desktop-notification"], [data-slot="desktop-notification-stack"].

Do / Don'tCopy Anchor Link

• Do ask with NotificationPermissionPrompt after the user did something that makes alerts useful, not on first load.
• Do keep titles short: real systems cut them off.
• Don't rely on this card to deliver alerts. It only draws them.
• Don't ask again after denied: show how to unblock instead.

RelatedCopy Anchor Link

• Toast
• NotificationItem
• NotificationCenter