useWebShare

browser

Installation

npx usehooks-cli@latest add use-web-share

Description

A React hook for sharing content using the Web Share API. Provides native sharing capabilities with comprehensive error handling and support detection.

Return Type

UseWebShareReturn

Property	Type	Description
isLoading	boolean	Whether a share operation is currently in progress
error	string \| null	Error message if sharing failed
isSupported	boolean	Whether the Web Share API is supported in the current browser
share	(data: ShareData) => Promise<boolean>	Function to share content, returns true if successful
canShare	(data?: ShareData) => boolean	Function to check if specific data can be shared
clearError	() => void	Function to clear the current error state

Examples

Share article content

Basic sharing functionality with error handling

import { useWebShare } from '@usehooks.io/use-web-share';

function ArticleShare() {
  const { share, canShare, isLoading, error, isSupported, clearError } = useWebShare();

  const shareArticle = async () => {
    const shareData = {
      title: 'Amazing Article',
      text: 'Check out this amazing article!',
      url: window.location.href
    };

    if (canShare(shareData)) {
      const success = await share(shareData);
      if (success) {
        console.log('Article shared successfully!');
      }
    }
  };

  if (!isSupported) {
    return <div>Web Share API not supported</div>;
  }

  return (
    <div>
      <button onClick={shareArticle} disabled={isLoading}>
        {isLoading ? 'Sharing...' : 'Share Article'}
      </button>
      
      {error && (
        <div style={{ color: 'red' }}>
          Error: {error}
          <button onClick={clearError}>Clear</button>
        </div>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Web Share API requires user activation (user gesture) to work
•File sharing support varies by browser and platform
•At least one of title, text, url, or files must be provided
•Provides detailed error messages for different failure scenarios
•Share targets depend on installed apps and browser capabilities

Implementation

'use client';

import { useState, useCallback } from "react";

interface ShareData {
  title?: string;
  text?: string;
  url?: string;
  files?: File[];
}

interface UseWebShareReturn {
  isLoading: boolean;
  error: string | null;
  isSupported: boolean;
  share: (data: ShareData) => Promise<boolean>;
  canShare: (data?: ShareData) => boolean;
  clearError: () => void;
}

export const useWebShare = (): UseWebShareReturn => {
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  // Check if Web Share API is supported
  const isSupported =
    typeof navigator !== "undefined" &&
    "share" in navigator &&
    typeof navigator.share === "function";

  // Check if data can be shared
  const canShare = useCallback(
    (data?: ShareData): boolean => {
      if (!isSupported || !navigator.canShare) {
        return false;
      }

      if (!data) {
        return true;
      }

      try {
        return navigator.canShare(data);
      } catch {
        return false;
      }
    },
    [isSupported]
  );

  // Share data using the Web Share API
  const share = useCallback(
    async (data: ShareData): Promise<boolean> => {
      if (!isSupported || !navigator.share) {
        setError("Web Share API is not supported");
        return false;
      }

      // Validate that at least one known property is provided
      if (!data.title && !data.text && !data.url && !data.files?.length) {
        setError("At least one of title, text, url, or files must be provided");
        return false;
      }

      // Check if the data can be shared
      if (navigator.canShare && !navigator.canShare(data)) {
        setError("The provided data cannot be shared");
        return false;
      }

      try {
        setIsLoading(true);
        setError(null);

        await navigator.share(data);
        return true;
      } catch (err) {
        let errorMessage = "Failed to share";

        if (err instanceof Error) {
          // Handle specific error cases
          switch (err.name) {
            case "InvalidStateError":
              errorMessage =
                "Document is not fully active or other sharing operations are in progress";
              break;
            case "NotAllowedError":
              errorMessage =
                "Sharing is not allowed. This may be due to permissions policy, lack of user activation, or security restrictions";
              break;
            case "TypeError":
              errorMessage =
                "The share data is invalid. Check that URLs are properly formatted and data is valid";
              break;
            case "AbortError":
              errorMessage =
                "Share was cancelled by the user or no share targets are available";
              break;
            case "DataError":
              errorMessage =
                "There was a problem starting the share target or transmitting the data";
              break;
            default:
              errorMessage =
                err.message || "An unknown error occurred while sharing";
          }
        }

        setError(errorMessage);
        return false;
      } finally {
        setIsLoading(false);
      }
    },
    [isSupported]
  );

  // Clear error state
  const clearError = useCallback(() => {
    setError(null);
  }, []);

  return {
    isLoading,
    error,
    isSupported,
    share,
    canShare,
    clearError,
  };
};

useStorage

CLI Docs All Hooks

useDebounce