Overlay

Notification

Persistent, rich notification cards stacked in the top-end viewport. Wrap the app in NotificationProvider and call useNotification(); cards stay until closed unless a duration is given.

Import

import { NotificationProvider, useNotification, Notification } from "@zephora/react";

Examples

Firing notifications

`useNotification()` returns `notify(options)`. Notifications are persistent by default; pass `duration` for auto-dismiss.

function App() {
  return (
    <NotificationProvider>
      <Buttons />
    </NotificationProvider>
  );
}

function Buttons() {
  const { notify } = useNotification();
  return (
    <>
      <Button
        onClick={() =>
          notify({
            title: "Deploy finished",
            description: "web-prod rolled out to 12 regions.",
            status: "success",
          })
        }
      >
        Notify success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          notify({
            title: "Disk almost full",
            description: "Volume /data is at 92% capacity.",
            status: "warning",
            duration: 6000,
          })
        }
      >
        Auto-dismiss warning
      </Button>
    </>
  );
}

Action buttons

`actions` renders buttons under the description; `dismiss(id)` closes a card.

function UpdateButton() {
  const { notify, dismiss } = useNotification();
  return (
    <Button
      variant="soft"
      onClick={() => {
        const id = notify({
          title: "Update available",
          description: "Version 2.4.0 is ready to install.",
          status: "info",
          actions: [
            { label: "Install", onClick: () => dismiss(id) },
            { label: "Later", onClick: () => dismiss(id) },
          ],
        });
      }}
    >
      Notify with actions
    </Button>
  );
}

Standalone Notification card

Weekly report ready

Your analytics digest for June is available.

<Notification
  title="Weekly report ready"
  description="Your analytics digest for June is available."
  status="info"
  onClose={() => console.log("closed")}
/>

API

NotificationProvider props

Prop	Type	Default	Description
`max`	`number`	—	Maximum number of cards shown at once; older notifications collapse into a "+N more" line. Auto-dismiss timers keep running for collapsed cards.
`placement`	`"top-end" \| "top-start" \| "bottom-end" \| "bottom-start"`	`"top-end"`	Viewport corner where notification cards stack.
`unstyled`	`boolean`	`false`	Headless mode — skips Zephora styling.

useNotification() props

Prop	Type	Default	Description
`notify(options)`	`(options: NotificationOptions) => string`	—	Shows a notification and returns its id.
`update(id, options)`	`(id: string, options: Partial<NotificationOptions>) => void`	—	Re-renders an existing notification in place; restarts the timer if duration is provided.
`dismiss(id)`	`(id: string) => void`	—	Removes the notification with the given id.

useNotification() → notify(options) props

Prop	Type	Default	Description
`title` *	`ReactNode`	—	Card heading.
`description`	`ReactNode`	—	Supporting text under the title.
`status`	`"info" \| "success" \| "warning" \| "danger"`	`"info"`	Semantic tone; danger announces assertively.
`icon`	`ReactNode`	—	Optional leading icon.
`actions`	`Array<{ label: string; onClick: () => void }>`	—	Action buttons rendered under the description.
`duration`	`number \| null`	`null`	Auto-dismiss delay in ms. null keeps the card until explicitly closed. The timer runs at the provider level (so it fires even while collapsed behind max) and pauses while the pointer hovers the card.

Notification (standalone) props

Prop	Type	Default	Description
`title` *	`ReactNode`	—	Card heading.
`description`	`ReactNode`	—	Supporting text.
`status`	`"info" \| "success" \| "warning" \| "danger"`	`"info"`	Semantic tone.
`icon`	`ReactNode`	—	Optional leading icon.
`actions`	`Array<{ label: string; onClick: () => void }>`	—	Action buttons under the description.
`duration`	`number \| null`	`null`	Auto-dismiss delay in ms (requires onClose); null = persistent.
`onClose`	`() => void`	—	Renders the close button and is called on close / when the timer fires.
`unstyled`	`boolean`	`false`	Headless mode.