Designing Contextual Permission Prompts

This guide is part of Permission Flows & Progressive Enhancement.

Contextual permission prompts convert at a higher rate because they arrive when the user already intends to act, not as a cold interruption. Without deliberate trigger timing and state management, native sharing dialogs appear at wrong moments, accumulate unhandled rejections, and leave broken UI behind when users cancel. This guide walks through every layer of the pattern: secure context gating, gesture binding, payload validation, error classification, and deterministic fallback routing.

Prerequisites

Before any share UI is rendered, confirm all three conditions are true:

• Secure context — window.isSecureContext === true (HTTPS or localhost)
• API presence — typeof navigator.share === 'function'
• Gesture scope — the eventual navigator.share() call is inside a direct click or pointerdown handler

If the first two checks fail, skip share UI entirely and show the fallback UI from the start. Never render a share button that will always fail.

Browser Support Snapshot

Permission Prompt Lifecycle Diagram

Step-by-Step Implementation

Step 1 — Gate on secure context and API availability

Render share UI only when both checks pass. Conditionally hiding the button prevents DOM bloat and eliminates dead click handlers on Firefox and HTTP pages.

export function isShareSupported() {
  return (
    typeof navigator !== 'undefined' &&
    typeof navigator.share === 'function' &&
    window.isSecureContext === true
  );
}

export function initShareButton(buttonEl, fallbackEl) {
  if (!isShareSupported()) {
    buttonEl.hidden = true;
    fallbackEl.hidden = false;
    return;
  }
  buttonEl.hidden = false;
  fallbackEl.hidden = true;
}

Defer all further initialisation until this gate passes. If it fails, route immediately to a copy-to-clipboard fallback or an SMS/email fallback URI.

Step 2 — Bind the share call to a direct user gesture

Native sharing must be triggered inside a click or pointerdown handler. Browsers block any navigator.share() call that occurs outside an active user interaction, throwing NotAllowedError.

Do not call navigator.share() from:

• setTimeout / setInterval callbacks
• Promises resolved after the gesture event has propagated
• IntersectionObserver or scroll callbacks
• Page load or DOMContentLoaded

export function bindShareTrigger(buttonEl, getPayload) {
  buttonEl.addEventListener('click', async (event) => {
    event.preventDefault();
    const payload = getPayload(); // assembled at gesture time, not at init
    await invokeShare(payload, buttonEl);
  });
}

Step 3 — Validate the payload with navigator.canShare() before invoking

navigator.canShare() performs a synchronous pre-flight against the browser’s supported MIME types and field constraints. Call it before navigator.share() to catch DataError without opening a native dialog.

export function sanitizePayload({ title, text, url, files }) {
  const result = {};
  if (title) result.title = String(title).trim();
  if (text)  result.text  = String(text).trim();
  if (url) {
    try {
      result.url = new URL(url).toString();
    } catch {
      throw new DOMException('Invalid URL in share payload.', 'DataError');
    }
  }
  if (files && Array.isArray(files)) result.files = files;
  return result;
}

export function isPayloadShareable(payload) {
  if (typeof navigator.canShare !== 'function') return true; // API absent, let share() decide
  return navigator.canShare(payload);
}

For a deeper walkthrough of navigator.canShare() including MIME allowlist behaviour, see implementing navigator.canShare() for graceful fallbacks.

Step 4 — Invoke share with loading state and aria-busy

Set aria-busy="true" on the trigger immediately so assistive technology communicates the pending state. The finally block guarantees cleanup regardless of outcome.

export async function invokeShare(rawPayload, buttonEl) {
  if (buttonEl.dataset.sharing === 'true') return; // guard against double-tap
  buttonEl.dataset.sharing = 'true';
  buttonEl.setAttribute('aria-busy', 'true');

  try {
    const payload = sanitizePayload(rawPayload);

    if (!isPayloadShareable(payload)) {
      handleFallback(payload);
      return;
    }

    await navigator.share(payload);
    logShareTelemetry('share_success');
  } catch (err) {
    handleShareError(err, rawPayload);
  } finally {
    delete buttonEl.dataset.sharing;
    buttonEl.removeAttribute('aria-busy');
    buttonEl.focus();
  }
}

Step 5 — Classify errors and route accordingly

The Web Share API produces three meaningful error types. Treating all of them the same way produces either excessive fallback triggers or missed recovery opportunities.

export function handleShareError(err, payload) {
  switch (err.name) {
    case 'AbortError':
      // User dismissed the dialog — no fallback needed, no log required
      return;

    case 'NotAllowedError':
      // Browser or OS blocked the share (gesture violation or permissions policy)
      handleFallback(payload);
      logShareTelemetry('share_denied');
      break;

    case 'DataError':
    case 'TypeError':
      // Payload rejected — bad MIME type or malformed field
      console.warn('[Share] Payload rejected:', err.message);
      handleFallback(payload);
      logShareTelemetry('share_data_error');
      break;

    default:
      console.error('[Share] Unexpected error:', err);
      handleFallback(payload);
  }
}

Step 6 — Implement the fallback dispatcher

When native sharing fails or is unavailable, preserve user intent by routing to an appropriate alternative. For prompts that have been denied multiple times, see handling permission denials gracefully for exponential backoff and degradation strategies.

export function handleFallback(payload) {
  // Clipboard fallback for text and URL payloads
  const clipboardText = payload.url || payload.text || '';
  if (clipboardText && navigator.clipboard?.writeText) {
    navigator.clipboard.writeText(clipboardText).catch(() => {});
  }

  // Dispatch a custom event so host components can surface a fallback UI
  document.dispatchEvent(
    new CustomEvent('share:fallback', { detail: payload, bubbles: true })
  );
}

function logShareTelemetry(event) {
  if ('sendBeacon' in navigator) {
    navigator.sendBeacon('/api/telemetry/share', JSON.stringify({ event }));
  }
}

Complete Class-Based Implementation

The steps above compose into a production-ready module. This version adds double-invocation protection and session-level dismissal tracking using sessionStorage — which resets on new sessions, unlike localStorage.

/**
 * ContextualShareManager
 * Web Share API orchestration with feature gating, payload validation,
 * error classification, and deterministic fallback routing.
 */
export class ContextualShareManager {
  #isSupported;
  #isSharing = false;
  #dismissalKey = 'share_dismissals';

  constructor() {
    this.#isSupported =
      typeof navigator !== 'undefined' &&
      typeof navigator.share === 'function' &&
      window.isSecureContext === true;
  }

  /**
   * Binds share logic to a trigger element.
   * @param {HTMLElement} triggerEl
   * @param {() => { title?: string, text?: string, url?: string, files?: File[] }} getPayload
   */
  bindTrigger(triggerEl, getPayload) {
    if (!this.#isSupported) {
      triggerEl.addEventListener('click', () => this.#executeFallback(getPayload()));
      return;
    }

    triggerEl.addEventListener('click', async (event) => {
      event.preventDefault();
      await this.#invokeNativeShare(getPayload(), triggerEl);
    });
  }

  async #invokeNativeShare(rawPayload, triggerEl) {
    if (this.#isSharing) return;
    this.#isSharing = true;
    triggerEl.setAttribute('aria-busy', 'true');

    try {
      const payload = this.#sanitizePayload(rawPayload);

      if (typeof navigator.canShare === 'function' && !navigator.canShare(payload)) {
        this.#executeFallback(rawPayload);
        return;
      }

      await navigator.share(payload);
      this.#logTelemetry('share_success');
    } catch (err) {
      this.#handleShareError(err, rawPayload);
    } finally {
      this.#isSharing = false;
      triggerEl.removeAttribute('aria-busy');
      triggerEl.focus();
    }
  }

  #sanitizePayload({ title, text, url, files }) {
    const out = {};
    if (title) out.title = String(title).trim();
    if (text)  out.text  = String(text).trim();
    if (url) {
      try {
        out.url = new URL(url).toString();
      } catch {
        throw new DOMException('Invalid URL in share payload.', 'DataError');
      }
    }
    if (Array.isArray(files)) out.files = files;
    return out;
  }

  #handleShareError(err, payload) {
    switch (err.name) {
      case 'AbortError':
        this.#incrementDismissalCount();
        return; // expected user behaviour — no fallback
      case 'NotAllowedError':
        this.#executeFallback(payload);
        this.#logTelemetry('share_denied');
        break;
      case 'DataError':
      case 'TypeError':
        console.warn('[Share] Payload rejected:', err.message);
        this.#executeFallback(payload);
        this.#logTelemetry('share_data_error');
        break;
      default:
        console.error('[Share] Unexpected failure:', err);
        this.#executeFallback(payload);
    }
  }

  #executeFallback(payload) {
    const text = payload.url || payload.text || '';
    if (text && navigator.clipboard?.writeText) {
      navigator.clipboard.writeText(text).catch(() => {});
    }
    document.dispatchEvent(
      new CustomEvent('share:fallback', { detail: payload, bubbles: true })
    );
  }

  #incrementDismissalCount() {
    const current = Number(sessionStorage.getItem(this.#dismissalKey) || 0);
    sessionStorage.setItem(this.#dismissalKey, String(current + 1));
  }

  getDismissalCount() {
    return Number(sessionStorage.getItem(this.#dismissalKey) || 0);
  }

  #logTelemetry(event) {
    if ('sendBeacon' in navigator) {
      navigator.sendBeacon('/api/telemetry/share', JSON.stringify({ event }));
    }
  }
}

Payload Validation and Error Boundary

navigator.canShare() is a synchronous guard that browsers evaluate against their internal MIME type allowlist without opening a native dialog. Always call it when sharing files. For text-only payloads on older Chrome or Safari, the method may be absent — the typeof check prevents a TypeError.

Platform Gotchas

iOS Safari

• File sharing requires iOS 14 or later.
• The MIME allowlist is stricter than Chrome Android. canShare() returns false for text/html files; prefer plain text or PDF.
• The share sheet on iOS opens immediately on button tap with no intermediate loading state — aria-busy will not be visible long enough to matter on fast devices.
• HTTPS is mandatory. localhost is not a secure context on a physical iOS device, so test with a self-signed certificate via an mDNS hostname.

Chrome Android

• Desktop Chrome does not support file sharing. navigator.canShare({ files: [...] }) returns false and navigator.share({ files: [...] }) throws DataError on all desktop Chrome builds.
• Chrome enforces a single active share session. If navigator.share() is called while another share dialog is already open, the call is silently dropped. The #isSharing guard above prevents this.

Desktop Safari (macOS 15+)

• The macOS share sheet has fewer installed share destinations than mobile, so users may see only Mail, AirDrop, and Notes. This is expected OS behaviour.
• Text and URL payloads work reliably. File sharing was added alongside macOS Ventura but has the same MIME restrictions as iOS.

Firefox

• The Web Share API ships behind a flag in Firefox and is not available in production builds. Detecting typeof navigator.share === 'function' will return false on all shipping Firefox versions. Never assume a user on desktop Firefox can share natively. Route them to the QR code fallback or an SMS/email link.

Testing and Verification

Chrome DevTools (desktop)

1. Open DevTools → Application → Manifest.
2. Add a custom share handler via the “Add to home screen” flow in a PWA if you need to test the share target side.
3. For gesture testing: navigator.share() can be called from the DevTools console only when the page’s top-level frame has recently had user interaction (click into the page first).

Physical device checklist

• iOS 14+ Safari: confirm file MIME types are accepted via canShare() before share()
• Android Chrome: verify fallback activates correctly on a page served over HTTP (not HTTPS)
• Test on a slow network to confirm aria-busy state renders correctly and the button is inert during the pending share
• Dismiss the native dialog and verify baseline UI restores and the share button is focusable again
• Trigger NotAllowedError by using a setTimeout call and verify the fallback fires (use a local test harness, not production telemetry)

For timing strategies that align prompts with natural user workflows and reduce repeated dismissals, see how to avoid permission fatigue in progressive web apps.

Common Pitfalls

• Gesture context violations — calling navigator.share() inside a resolved Promise chain breaks the gesture linkage in Safari. Keep the await navigator.share() call in the same synchronous execution as the event handler.
• Misclassifying AbortError — treating user cancellation as a fatal error and triggering a fallback or an error toast is a UX anti-pattern. AbortError is the expected, healthy path when a user changes their mind.
• Rendering share UI without feature detection — hardcoding a share button on all browsers leaves a non-functional element visible on Firefox and HTTP pages.
• Ignoring canShare() for files — calling navigator.share({ files: [...] }) without a canShare() pre-check will throw DataError silently on unsupported MIME types.
• Assembling File arrays at component initialisation — constructing large File objects before the user has clicked adds unnecessary memory pressure. Defer payload assembly to inside the click handler.
• Storing payloads in localStorage — share payloads may contain sensitive titles or URLs. Use sessionStorage for transient state and never persist raw payloads across sessions.

FAQ

Related

• Permission Flows & Progressive Enhancement — parent section
• How to avoid permission fatigue in progressive web apps — timing strategies for fewer dismissals
• Handling Permission Denials Gracefully — degradation and exponential backoff
• Implementing exponential backoff for permission re-prompts
• SMS and Email Fallback Architectures — deterministic fallback paths
• QR code generation for cross-device sharing — visual fallback for desktop users