use-notifications (use-notifications)

A React hook for managing browser notifications with comprehensive feature detection and fallback support

v0.1.0

Usage

import { use-notifications } from "@/hooks"

"use client";

import {
  AlertCircleIcon,
  BellIcon,
  CheckCircle2Icon,
  XCircleIcon,
} from "lucide-react";

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

import { useNotifications } from "@/components/hooks/use-notifications";

export function UseNotificationsDemo() {
  const {
    permission,
    requestPermission,
    showNotification,
    isSupported,
    isSecureContext,
    supportsActions,
    supportsBadge,
    supportsImage,
    supportsVibrate,
    supportsSound,
  } = useNotifications();

  const handleRequestPermission = async () => {
    try {
      await requestPermission();
    } catch (error) {
      console.error("Failed to request permission:", error);
    }
  };

  const handleShowNotification = () => {
    showNotification("Demo Notification", {
      body: "This is a test notification from the demo component",
      icon: "/favicon.ico",
      badge: "/favicon.ico",
      image: "/favicon.ico",
      // Actions are only supported with Service Worker
      // actions: [
      //   {
      //     action: 'view',
      //     title: 'View Details',
      //   },
      // ],
    });
  };

  return (
    <Card className="relative max-w-2xl w-full">
      <CardHeader>
        <CardTitle className="flex items-center gap-2">
          <BellIcon className="h-5 w-5" />
          useNotifications
        </CardTitle>
        <CardDescription>
          This component demonstrates the use of the{" "}
          <code>useNotifications</code> hook to manage browser notifications.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="space-y-2">
          <h3 className="font-medium">Browser Support</h3>
          <div className="flex flex-wrap gap-2">
            <Badge variant={isSupported ? "default" : "destructive"}>
              {isSupported ? "Supported" : "Not Supported"}
            </Badge>
            <Badge variant={isSecureContext ? "default" : "destructive"}>
              {isSecureContext ? "Secure Context" : "Not Secure"}
            </Badge>
          </div>
        </div>

        <div className="space-y-2">
          <h3 className="font-medium">Feature Support</h3>
          <div className="flex flex-wrap gap-2">
            <Badge variant={supportsActions ? "default" : "secondary"}>
              Actions {supportsActions ? "✓" : "✗"}
            </Badge>
            <Badge variant={supportsBadge ? "default" : "secondary"}>
              Badge {supportsBadge ? "✓" : "✗"}
            </Badge>
            <Badge variant={supportsImage ? "default" : "secondary"}>
              Image {supportsImage ? "✓" : "✗"}
            </Badge>
            <Badge variant={supportsVibrate ? "default" : "secondary"}>
              Vibrate {supportsVibrate ? "✓" : "✗"}
            </Badge>
            <Badge variant={supportsSound ? "default" : "secondary"}>
              Sound {supportsSound ? "✓" : "✗"}
            </Badge>
          </div>
        </div>

        <div className="space-y-2">
          <h3 className="font-medium">Permission Status</h3>
          <Badge
            variant={
              permission === "granted"
                ? "default"
                : permission === "denied"
                ? "destructive"
                : "secondary"
            }
          >
            {permission === "granted" ? (
              <CheckCircle2Icon className="mr-1 h-3 w-3" />
            ) : permission === "denied" ? (
              <XCircleIcon className="mr-1 h-3 w-3" />
            ) : (
              <AlertCircleIcon className="mr-1 h-3 w-3" />
            )}
            {permission.charAt(0).toUpperCase() + permission.slice(1)}
          </Badge>
        </div>

        {!isSupported && (
          <Alert variant="destructive">
            <AlertCircleIcon className="h-4 w-4" />
            <AlertTitle>Not Supported</AlertTitle>
            <AlertDescription>
              Your browser does not support the Notifications API. Consider
              using a fallback UI notification system.
            </AlertDescription>
          </Alert>
        )}

        {!isSecureContext && (
          <Alert variant="destructive">
            <AlertCircleIcon className="h-4 w-4" />
            <AlertTitle>Not Secure</AlertTitle>
            <AlertDescription>
              The Notifications API requires a secure context (HTTPS). Please
              use HTTPS to enable notifications.
            </AlertDescription>
          </Alert>
        )}

        {supportsActions && (
          <Alert variant="default">
            <AlertCircleIcon className="h-4 w-4" />
            <AlertTitle>Actions Support</AlertTitle>
            <AlertDescription>
              Note: Notification actions are only supported when using a Service
              Worker. This demo uses the basic Notification API without a
              Service Worker.
            </AlertDescription>
          </Alert>
        )}
      </CardContent>
      <CardFooter className="flex lg:flex-row items-start flex-col gap-2">
        <Button
          onClick={handleRequestPermission}
          disabled={!isSupported || !isSecureContext}
        >
          Request Permission
        </Button>
        <Button
          onClick={handleShowNotification}
          disabled={
            !isSupported || !isSecureContext || permission !== "granted"
          }
        >
          Show Notification
        </Button>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-notifications

Options

Name	Type	Default	Description
permission	'default' \| 'granted' \| 'denied'	—	Current notification permission status
isSupported	boolean	—	Whether the browser supports the Notifications API
isSecureContext	boolean	—	Whether the current context is secure (HTTPS)
supportsActions	boolean	—	Whether the browser supports notification actions
supportsBadge	boolean	—	Whether the browser supports notification badges
supportsImage	boolean	—	Whether the browser supports notification images
supportsVibrate	boolean	—	Whether the browser supports notification vibration
supportsSound	boolean	—	Whether the browser supports notification sounds
requestPermission	() => Promise<NotificationPermission>	—	Function to request notification permission
showNotification	(title: string, options?: NotificationOptions) => void	—	Function to show a notification
body	string	—	The body text of the notification
icon	string	—	The URL of an icon to display in the notification
image	string	—	The URL of an image to display in the notification
badge	string	—	The URL of an image used to represent the notification when there is not enough space
tag	string	—	An ID for a given notification that allows you to find, replace, or remove the notification
data	void	—	Arbitrary data that you want to associate with the notification
requireInteraction	boolean	—	Whether the notification should remain active until the user clicks or dismisses it
silent	boolean	—	Whether the notification should be silent
sound	string	—	The URL of an audio file to play with the notification
vibrate	number \| number[]	—	A vibration pattern for devices with vibration hardware
dir	'auto' \| 'ltr' \| 'rtl'	—	The direction of the notification's text
lang	string	—	The notification's language
renotify	boolean	—	Whether the user should be notified after a new notification replaces an old one
sticky	boolean	—	Whether the notification should be sticky
timestamp	number	—	The time at which the notification was created
actions	Array<{action: string, title: string, icon?: string}>	—	Actions to display in the notification
The	—	—	hook returns an object with the following properties
The	—	—	showNotification function accepts an optional options parameter

Browser Support

The Notifications API is supported in most modern browsers with varying feature support:
Chrome: Full support
Firefox: Full support
Safari: Partial support (some features may not be available)
Edge: Full support
Opera: Full support
Note: The API requires a secure context (HTTPS) to work, except for localhost.

Feature Detection

The hook automatically detects browser support for various notification features
Provides boolean flags for each supported feature
Handles cases where certain features might not be available
Gracefully degrades functionality based on browser capabilities

Permission Management

Tracks the current permission status
Provides a function to request permission
Handles permission changes across browser tabs
Manages permission state persistence

Best Practices & Caveats

Always check for browser support before using the hook
Request permission only after a user interaction
Provide clear feedback about the notification permission status
Implement fallback UI notifications for unsupported browsers
Use appropriate icons and badges to improve notification visibility
Consider the user's context when showing notifications
Handle notification errors gracefully
Clean up notifications when they're no longer needed

Files in this hook

Source	Destination
files/use-notifications.ts	src/hooks/use-notifications.ts