React Hook prompting the user to "Add to homescreen" 🏠 #PWA #React

POST.md

title	slug	createdAt	language	preview
React Hook prompting the user to "Add to homescreen"	react-hook-prompting-the-user-to-add	2018-11-29T20:35:02Z	en	Simple React Hook for showing the user a custom "Add to homescreen" prompt.

React Hook for showing custom "Add to homescreen" prompt

Demo:
Twitter

Simple React Hook for showing the user a custom "Add to homescreen" prompt.

const [prompt, promptToInstall] = useAddToHomescreenPrompt();

Listens for beforeinstallprompt event, which notifies you when the browser would have shown the default dialog, intercepts it and lets you take over and show the prompt when ever you please.

Browser support and requirements

Add to Home Screen

Browser support is still quite lacking. At the time of writing, only Chrome (Desktop + Android) is supported.

Implementation

import * as React from "react";

interface IBeforeInstallPromptEvent extends Event {
  readonly platforms: string[];
  readonly userChoice: Promise<{
    outcome: "accepted" | "dismissed";
    platform: string;
  }>;
  prompt(): Promise<void>;
}

export function useAddToHomescreenPrompt(): [
  IBeforeInstallPromptEvent | null,
  () => void
] {
  const [prompt, setState] = React.useState<IBeforeInstallPromptEvent | null>(
    null
  );

  const promptToInstall = () => {
    if (prompt) {
      return prompt.prompt();
    }
    return Promise.reject(
      new Error(
        'Tried installing before browser sent "beforeinstallprompt" event'
      )
    );
  };

  React.useEffect(() => {
    const ready = (e: IBeforeInstallPromptEvent) => {
      e.preventDefault();
      setState(e);
    };

    window.addEventListener("beforeinstallprompt", ready as any);

    return () => {
      window.removeEventListener("beforeinstallprompt", ready as any);
    };
  }, []);

  return [prompt, promptToInstall];
}

Example component

import * as React from "react";
import { useAddToHomescreenPrompt } from "./useAddToHomescreenPrompt";

export function ExampleComponent() {
  const [prompt, promptToInstall] = useAddToHomescreenPrompt();
  const [isVisible, setVisibleState] = React.useState(false);

  const hide = () => setVisibleState(false);

  React.useEffect(
    () => {
      if (prompt) {
        setVisibleState(true);
      }
    },
    [prompt]
  );

  if (!isVisible) {
    return <div />;
  }

  return (
    <div onClick={hide}>
      <button onClick={hide}>Close</button>
      Hello! Wanna add to homescreen?
      <button onClick={promptToInstall}>Add to homescreen</button>
    </div>
  );
}

If I'm not mistaken the event is triggered once onload so you can only use that effect in your root app component if you have different routes. (which is no big deal since we can pass prompt and promptinstall as props to child components)

Good point! I guess the default use case would be to use this only once per application, but it would still be possible to refactor this to work with many calls in the component tree.

Hey man, it works perfect, thanks a lot!

Glad you liked it :)

Good point! I guess the default use case would be to use this only once per application, but it would still be possible to refactor this to work with many calls in the component tree.

please do so 👍

Couldn't get it to work :\

Couldn't get it to work :\

Check that your app meets the requirements of the home screen prompt https://web.dev/install-criteria/

Check that your app meets the requirements of the home screen prompt https://web.dev/install-criteria/

You were right, it was because I had wrong path for the icons. I thought the manifest was showing warnings but it was actually errors.

It works as expected! Thank you for your work @rikukissa

Good to hear :)

Hey! Thanks for this example! Still no support on other browsers other than Chrome? Thanks

@jasoft92 The support is from the browsers itself. You can check it here https://caniuse.com/#feat=web-app-manifest

@loxator thanks for the link - very useful! Yes that is what I was referring to, which other browsers support it and it's a pity to see so very little support from other major browsers.

I ended up wrapping it in a context.

Provider/Consumer

// PromptToInstallProvider.tsx
import React, { createContext, useEffect, useContext, useCallback } from 'react';
import { Children, IBeforeInstallPromptEvent, PromptCtx } from './types';

const PromptToInstall = createContext<PromptCtx>({deferredEvt: null});

export function PromptToInstallProvider(props: Children) {
  const [deferredEvt, setDeferredEvt] = React.useState<IBeforeInstallPromptEvent | null>(
    null,
  );

  const hidePrompt = useCallback(() => {
    setDeferredEvt(null);
  }, []);

  useEffect(() => {
    const ready = (e: IBeforeInstallPromptEvent) => {
      e.preventDefault();
      setDeferredEvt(e);
    };

    window.addEventListener('beforeinstallprompt', ready as any);

    return () => {
      window.removeEventListener('beforeinstallprompt', ready as any);
    };
  }, []);

  return (
    <PromptToInstall.Provider value={{deferredEvt, hidePrompt}}>
      {props.children}
    </PromptToInstall.Provider>
  );
}

export function usePromptToInstall() {
  const ctx = useContext(PromptToInstall);
  if (!ctx) {
    throw new Error('Cannot use usePromptToInstall() outside <PromptToInstallProvider />');
  }
  return ctx;
}

Example

import React from 'react';
import { usePromptToInstall } from 'shared/providers/propmptToInstall';

export default function InstallPrompt() {
  const { deferredEvt, hidePrompt } = usePromptToInstall();

  if (!deferredEvt) {
    return null;
  }
  return (
      <span>
        <p>Install app to your device?</p>
        <div>
          <button onClick={deferredEvt.prompt}>Yes</button>
          <button onClick={hidePrompt}>No, hide message</button>
        </div>
      </span>
  );
}

Types used

// types.ts
export interface IBeforeInstallPromptEvent extends Event {
  readonly platforms: string[];
  readonly userChoice: Promise<{
    outcome: 'accepted' | 'dismissed';
    platform: string;
  }>;
  prompt(): Promise<void>;
}
export type PromptCtx = {
  deferredEvt: IBeforeInstallPromptEvent | null;
  hidePrompt?:() => void;
};
export type Children = {
  children: ReactElement | ReactElement[] | string | null;
};

It is not working on my project...
It is giving an error says:--
Type annotations can only be used in TypeScript files.

@Shubham0850 It's a Typescript file. You need to remove the types assigned to it to make it work with JS. Or you could copy the file and name it with a .ts extension

I ended up wrapping it in a context.

Provider/Consumer

// PromptToInstallProvider.tsx
import React, { createContext, useEffect, useContext, useCallback } from 'react';
import { Children, IBeforeInstallPromptEvent, PromptCtx } from './types';

const PromptToInstall = createContext<PromptCtx>({deferredEvt: null});

export function PromptToInstallProvider(props: Children) {
  const [deferredEvt, setDeferredEvt] = React.useState<IBeforeInstallPromptEvent | null>(
    null,
  );

  const hidePrompt = useCallback(() => {
    setDeferredEvt(null);
  }, []);

  useEffect(() => {
    const ready = (e: IBeforeInstallPromptEvent) => {
      e.preventDefault();
      setDeferredEvt(e);
    };

    window.addEventListener('beforeinstallprompt', ready as any);

    return () => {
      window.removeEventListener('beforeinstallprompt', ready as any);
    };
  }, []);

  return (
    <PromptToInstall.Provider value={{deferredEvt, hidePrompt}}>
      {props.children}
    </PromptToInstall.Provider>
  );
}

export function usePromptToInstall() {
  const ctx = useContext(PromptToInstall);
  if (!ctx) {
    throw new Error('Cannot use usePromptToInstall() outside <PromptToInstallProvider />');
  }
  return ctx;
}

Example

import React from 'react';
import { usePromptToInstall } from 'shared/providers/propmptToInstall';

export default function InstallPrompt() {
  const { deferredEvt, hidePrompt } = usePromptToInstall();

  if (!deferredEvt) {
    return null;
  }
  return (
      <span>
        <p>Install app to your device?</p>
        <div>
          <button onClick={deferredEvt.prompt}>Yes</button>
          <button onClick={hidePrompt}>No, hide message</button>
        </div>
      </span>
  );
}

Types used

// types.ts
export interface IBeforeInstallPromptEvent extends Event {
  readonly platforms: string[];
  readonly userChoice: Promise<{
    outcome: 'accepted' | 'dismissed';
    platform: string;
  }>;
  prompt(): Promise<void>;
}
export type PromptCtx = {
  deferredEvt: IBeforeInstallPromptEvent | null;
  hidePrompt?:() => void;
};
export type Children = {
  children: ReactElement | ReactElement[] | string | null;
};

Always getting TypeError: Failed to execute 'prompt' on 'BeforeInstallPromptEvent': Illegal invocation, when I'm trying to use deferredEvt.prompt, event if the functions is defined. What can be the problem?

Weird! This error (Illegal invocation) seems to refer to the context in which the function is being executed (gathered from this SO answer).

I just tried it again on Chrome browser (Mac OS) and it worked
The only difference I have is

const onInstall = () => {
    if (deferredEvt?.prompt) {
      deferredEvt.prompt();
      invalidateEvt(); 
    } else if (BROWSER.isSafariMobile) {
      setShowIOSBox(true);
    }
};

If you have a minimal reproduceable codebase, I can look into it further

Hi, I added a listener for the appinstalled event and made the hook return a third boolean flag

import * as React from "react";

interface IBeforeInstallPromptEvent extends Event {
  readonly platforms: string[];
  readonly userChoice: Promise<{
    outcome: "accepted" | "dismissed";
    platform: string;
  }>;
  prompt(): Promise<void>;
}

export function useAddToHomescreenPrompt(): [
  IBeforeInstallPromptEvent | null,
  () => void,
  boolean
] {
  const [
    promptable,
    setPromptable,
  ] = React.useState<IBeforeInstallPromptEvent | null>(null);

  const [isInstalled, setIsInstalled] = React.useState(false);

  const promptToInstall = () => {
    if (promptable) {
      return promptable.prompt();
    }
    return Promise.reject(
      new Error(
        'Tried installing before browser sent "beforeinstallprompt" event'
      )
    );
  };

  React.useEffect(() => {
    const ready = (e: IBeforeInstallPromptEvent) => {
      e.preventDefault();
      setPromptable(e);
    };

    window.addEventListener("beforeinstallprompt", ready as any);

    return () => {
      window.removeEventListener("beforeinstallprompt", ready as any);
    };
  }, []);

  React.useEffect(() => {
    const onInstall = () => {
      setIsInstalled(true);
    };

    window.addEventListener("appinstalled", onInstall as any);

    return () => {
      window.removeEventListener("appinstalled", onInstall as any);
    };
  }, []);

  return [promptable, promptToInstall, isInstalled];
}

import * as React from "react";
import { useAddToHomescreenPrompt } from "./useAddToHomescreenPrompt";
import styled from "@emotion/styled";

const ButtonElement = styled.button({
  // style
});

export function AddToHomescreenButton() {
  const [promptable, promptToInstall, isInstalled] = useAddToHomescreenPrompt();

  return promptable && !isInstalled ? (
    <ButtonElement onClick={promptToInstall}>INSTALL APP</ButtonElement>
  ) : null;
}

If I'm not mistaken the event is triggered once onload so you can only use that effect in your root app component if you have different routes. (which is no big deal since we can pass prompt and promptinstall as props to child components)

Using in footer component which is only available at some pages and prompt only happens if I reload page (sometimes fails even after page reload). Any more hints?

Thanks for this gist! For anyone that wants to avoid the any type:

React.useEffect(() => {
    const ready = (e: IBeforeInstallPromptEvent) => {
      e.preventDefault()
      setState(e)
    }

    window.addEventListener(
      "beforeinstallprompt",
      ready as EventListenerOrEventListenerObject
    )

    return () => {
      window.removeEventListener(
        "beforeinstallprompt",
        ready as EventListenerOrEventListenerObject
      )
    }
 }, [])

On the computer everything is fine, but on both Android and iOS phones it doesn't work