{
"$schema": "https://blode.co/ui/schema/registry-item.json",
"name": "add-to-homescreen",
"title": "Add to Homescreen",
"author": "Matthew Blode",
"description": "A sheet of platform-aware instructions for installing a web app to the home screen.",
"registryDependencies": ["button", "sheet", "@blode/copy-button", "@blode/use-install-prompt"],
"files": [
{
"path": "ui/add-to-homescreen.tsx",
"content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\nimport { useInstallPrompt } from \"@/hooks/use-install-prompt\";\nimport { Button } from \"@/components/ui/button\";\nimport { CopyButton } from \"@/components/ui/copy-button\";\nimport {\n Sheet,\n SheetContent,\n SheetDescription,\n SheetHeader,\n SheetTitle,\n} from \"@/components/ui/sheet\";\n\ntype AddToHomescreenPlatform = \"android\" | \"desktop\" | \"ios\";\n\ntype AddToHomescreenBrowser =\n | \"chrome\"\n | \"edge\"\n | \"facebook\"\n | \"firefox\"\n | \"instagram\"\n | \"linkedin\"\n | \"safari\"\n | \"samsung\"\n | \"twitter\"\n | \"unknown\";\n\n/** One numbered instruction. `glyph` is drawn inline, mid-sentence. */\ninterface AddToHomescreenStep {\n /** Small picture of the control the sentence names, shown inline. */\n glyph?: React.ReactNode;\n /** Sentence for this step. */\n text: React.ReactNode;\n}\n\ninterface AddToHomescreenMessages {\n /** Body of the fallback panel, when no recipe matches this browser. */\n fallbackBody: string;\n /** Heading of the fallback panel. */\n fallbackTitle: string;\n /** Accessible name of the copy-link button in the fallback panel. */\n copyLink: string;\n /** Label of the one-tap install button, where the browser offers one. */\n install: string;\n /** Sub-heading shown alongside the one-tap install button. */\n installSubtitle: string;\n /** Sub-heading under the title. */\n subtitle: string;\n /** Heading of the instruction panel. */\n title: (appName: string) => string;\n}\n\nconst DEFAULT_MESSAGES: AddToHomescreenMessages = {\n copyLink: \"Copy link\",\n fallbackBody:\n \"Open this page in Safari on iOS, or Chrome on Android, to add it to your home screen.\",\n fallbackTitle: \"Add this app to your home screen\",\n install: \"Install\",\n installSubtitle: \"It opens in its own window, like an app.\",\n subtitle: \"Two steps, and it opens like an app.\",\n title: (appName) => `Add ${appName} to your home screen`,\n};\n\n/*\n * Glyphs are drawn rather than imported so the item installs as one file. The\n * registry has no mechanism for copying assets, so a consumer of an -based\n * version would get broken links.\n */\n\nconst ShareGlyph = () => (\n \n);\n\nconst MenuGlyph = () => (\n \n);\n\nconst AddSquareGlyph = () => (\n \n);\n\n/** The bouncing pointer. Rotated by its wrapper, so it always draws upward. */\nconst ArrowGlyph = () => (\n \n);\n\nconst testUserAgent = (pattern: RegExp): boolean => {\n if (typeof window === \"undefined\" || !window.navigator) {\n return false;\n }\n\n const brands = (\n window.navigator as Navigator & {\n userAgentData?: { brands: { brand: string }[] };\n }\n ).userAgentData?.brands;\n\n return (\n Boolean(brands?.some((entry) => pattern.test(entry.brand))) ||\n pattern.test(window.navigator.userAgent)\n );\n};\n\nconst detectIsIos = (): boolean => {\n if (typeof window === \"undefined\") {\n return false;\n }\n\n // iPadOS 13+ reports itself as a Mac, and only the touch count gives it away.\n const isIpad = window.navigator.platform === \"MacIntel\" && window.navigator.maxTouchPoints > 1;\n return testUserAgent(/iPad|iPhone|iPod/u) || isIpad;\n};\n\nconst referrerMatches = (fragment: string): boolean =>\n typeof document !== \"undefined\" && document.referrer.includes(fragment);\n\n/**\n * Instagram and Threads render their in-app browser shorter than the screen and\n * do not brand the user agent, so the height gap is the only tell. It is a\n * heuristic: a browser with a persistent toolbar can produce the same gap.\n */\nconst looksLikeMetaInAppBrowser = (): boolean => {\n if (typeof window === \"undefined\") {\n return false;\n }\n\n if (referrerMatches(\"//l.instagram.com/\")) {\n return true;\n }\n\n return (\n testUserAgent(/iPhone/u) &&\n Boolean(window.screen.height) &&\n Boolean(window.outerHeight) &&\n window.outerHeight < window.screen.height\n );\n};\n\nconst detectBrowser = (platform: AddToHomescreenPlatform): AddToHomescreenBrowser => {\n // In-app webviews impersonate the system browser, so they are tested first.\n if (testUserAgent(/FBAN|FBAV/u)) {\n return \"facebook\";\n }\n if (testUserAgent(/LinkedInApp/u)) {\n return \"linkedin\";\n }\n\n if (platform === \"ios\") {\n if (referrerMatches(\"//t.co/\")) {\n return \"twitter\";\n }\n if (testUserAgent(/CriOS/u)) {\n return \"chrome\";\n }\n if (testUserAgent(/FxiOS/u)) {\n return \"firefox\";\n }\n if (testUserAgent(/EdgiOS/u)) {\n return \"edge\";\n }\n if (looksLikeMetaInAppBrowser()) {\n return \"instagram\";\n }\n return testUserAgent(/Safari/u) ? \"safari\" : \"unknown\";\n }\n\n if (platform === \"android\") {\n if (testUserAgent(/SamsungBrowser/u)) {\n return \"samsung\";\n }\n if (testUserAgent(/EdgA/u)) {\n return \"edge\";\n }\n if (testUserAgent(/Firefox/u)) {\n return \"firefox\";\n }\n return testUserAgent(/Chrome/u) ? \"chrome\" : \"unknown\";\n }\n\n // Desktop. Chrome, Edge and Safari can all install a page as an app.\n if (testUserAgent(/EdgA?\\b|Edg\\//u)) {\n return \"edge\";\n }\n if (testUserAgent(/Firefox/u)) {\n return \"firefox\";\n }\n if (testUserAgent(/Chrome|Chromium/u)) {\n return \"chrome\";\n }\n if (testUserAgent(/Safari/u)) {\n return \"safari\";\n }\n return \"unknown\";\n};\n\nconst detectPlatform = (): AddToHomescreenPlatform => {\n if (detectIsIos()) {\n return \"ios\";\n }\n return testUserAgent(/Android/u) ? \"android\" : \"desktop\";\n};\n\nconst detectInstalled = (): boolean => {\n if (typeof window === \"undefined\") {\n return false;\n }\n\n return (\n (window.navigator as Navigator & { standalone?: boolean }).standalone === true ||\n window.matchMedia(\"(display-mode: standalone)\").matches\n );\n};\n\ninterface Recipe {\n /**\n * Where the arrow points, or null when the control's position is a user\n * setting we cannot read. A wrong arrow is worse than none: the reader\n * trusts it, looks at the wrong edge, and stops trusting the steps too.\n */\n arrow: \"down\" | \"up\" | null;\n /** Which edge of the screen the sheet hugs. */\n edge: \"bottom\" | \"top\";\n steps: AddToHomescreenStep[];\n}\n\nconst MENU_HINT = \"You may need to scroll the menu to find it.\";\n\n/**\n * Recipes are keyed on where the browser actually keeps its install control,\n * researched per browser rather than assumed:\n *\n * - iOS Safari keeps Share in the bottom toolbar in all three layouts\n * (Bottom, Top and Compact); Compact only hides it behind a `...` button.\n * - iOS Chrome/Edge/Firefox put Share beside the address bar, which the user\n * can move to the top or the bottom. Undetectable, so no arrow.\n * - Android and desktop Chromium menus are pinned to the top right.\n * - Desktop Chrome and Edge show an install pill at the end of the address bar.\n * - macOS Safari installs through File > Add to Dock (Sonoma 14 and later).\n */\nconst getRecipe = (\n platform: AddToHomescreenPlatform,\n browser: AddToHomescreenBrowser,\n): Recipe | null => {\n const openInBrowser: Recipe = {\n // The in-app \"...\" moves between apps and versions, so it is described\n // rather than pointed at.\n arrow: null,\n edge: \"top\",\n steps: [\n { glyph: , text: \"Tap the menu in this app's browser bar.\" },\n { text: \"Choose Open in browser, then install it from there.\" },\n ],\n };\n\n if (browser === \"facebook\" || browser === \"linkedin\" || browser === \"instagram\") {\n return openInBrowser;\n }\n\n if (platform === \"ios\") {\n if (browser === \"twitter\") {\n return openInBrowser;\n }\n if (browser === \"safari\") {\n return {\n arrow: \"down\",\n edge: \"bottom\",\n steps: [\n {\n glyph: ,\n text: \"Tap Share in the toolbar below. In the compact layout, tap the ... button first.\",\n },\n { glyph: , text: `Choose Add to Home Screen. ${MENU_HINT}` },\n ],\n };\n }\n if (browser === \"chrome\" || browser === \"edge\" || browser === \"firefox\") {\n return {\n arrow: null,\n edge: \"bottom\",\n steps: [\n // \"Beside the address bar\" survives the user moving the address bar;\n // \"below\" would not.\n { glyph: , text: \"Tap Share, beside the address bar.\" },\n { glyph: , text: `Choose Add to Home Screen. ${MENU_HINT}` },\n ],\n };\n }\n return null;\n }\n\n if (platform === \"android\") {\n if (browser === \"chrome\" || browser === \"edge\" || browser === \"samsung\") {\n return {\n arrow: \"up\",\n edge: \"top\",\n steps: [\n { glyph: , text: \"Tap the menu at the top right.\" },\n // Chromium reserves \"Add to Home screen\" for plain shortcuts and\n // says \"Install app\" for a page that meets the install criteria.\n { glyph: , text: `Choose Install app. ${MENU_HINT}` },\n ],\n };\n }\n if (browser === \"firefox\") {\n return {\n arrow: \"up\",\n edge: \"top\",\n steps: [\n { glyph: , text: \"Tap the menu at the top right.\" },\n { glyph: , text: \"Choose Install, then Add to home screen.\" },\n ],\n };\n }\n return null;\n }\n\n if (browser === \"chrome\" || browser === \"edge\") {\n return {\n arrow: \"up\",\n edge: \"top\",\n steps: [\n {\n glyph: ,\n text: \"Click the install icon at the right of the address bar.\",\n },\n {\n glyph: ,\n text: \"If it is not there, open the menu and look for Install page as an app.\",\n },\n ],\n };\n }\n\n if (browser === \"safari\") {\n return {\n arrow: \"up\",\n edge: \"top\",\n steps: [\n { glyph: , text: \"Open the File menu at the top of the screen.\" },\n { glyph: , text: \"Choose Add to Dock, then click Add.\" },\n ],\n };\n }\n\n // Desktop Firefox has no install path, and neither does anything unplaced.\n return null;\n};\n\ninterface Detection {\n browser: AddToHomescreenBrowser;\n href: string;\n installed: boolean;\n platform: AddToHomescreenPlatform;\n}\n\n/** The bouncing pointer, placed just inside the edge the sheet hugs. */\nconst InstallArrow = ({ direction }: { direction: \"down\" | \"up\" }) => (\n \n \n \n \n \n);\n\n/**\n * Sniffing runs in an effect, never during render, so the server and the first\n * client render agree on \"nothing\" instead of flashing the wrong platform.\n */\nconst useDetection = (\n platformOverride: AddToHomescreenPlatform | undefined,\n browserOverride: AddToHomescreenBrowser | undefined,\n): Detection | null => {\n const [detection, setDetection] = React.useState(null);\n\n React.useEffect(() => {\n const platform = platformOverride ?? detectPlatform();\n // oxlint-disable-next-line react/react-compiler -- one-shot UA detection must run after mount so SSR and the first client render agree\n setDetection({\n browser: browserOverride ?? detectBrowser(platform),\n href: window.location.href,\n // An override means a demo is driving this, so the real install state\n // must not hide it.\n installed: platformOverride === undefined && detectInstalled(),\n platform,\n });\n }, [browserOverride, platformOverride]);\n\n return detection;\n};\n\n/** The numbered recipe. Three columns, so a wrapped line keeps its indent. */\nconst InstallSteps = ({ steps }: { steps: AddToHomescreenStep[] }) => (\n \n {steps.map((step, index) => (\n \n \n {index + 1}\n \n {step.glyph && (\n \n {step.glyph}\n \n )}\n {step.text}\n \n ))}\n \n);\n\ninterface TierInput {\n browser: AddToHomescreenBrowser;\n canInstall: boolean;\n platform: AddToHomescreenPlatform;\n platformOverride?: AddToHomescreenPlatform;\n showArrow: boolean;\n stepsOverride?: AddToHomescreenStep[];\n}\n\n/**\n * Picks the tier and the geometry that goes with it. Tier 0 is the browser's\n * own prompt: where Chromium has offered one we can replay, a single tap beats\n * any written instruction, so no steps and no arrow are drawn.\n */\nconst resolveTier = ({\n browser,\n canInstall,\n platform,\n platformOverride,\n showArrow,\n stepsOverride,\n}: TierInput) => {\n // An override means a demo is driving this, so the real prompt must not\n // pre-empt the recipe being demonstrated.\n const nativeInstall = canInstall && platformOverride === undefined;\n const recipe = getRecipe(platform, browser);\n const steps = stepsOverride ?? recipe?.steps;\n const direction = recipe?.arrow ?? null;\n // Caller-supplied steps describe an unknown control, so nothing is pointed at.\n const pointable = direction !== null && stepsOverride === undefined;\n\n return {\n direction,\n nativeInstall,\n side: recipe?.edge ?? \"top\",\n steps,\n withArrow: showArrow && pointable && !nativeInstall,\n };\n};\n\ninterface InstallPanelProps {\n appIconUrl?: string;\n detection: Detection;\n heading: string;\n messages: AddToHomescreenMessages;\n nativeInstall: boolean;\n onInstall: () => void;\n steps?: AddToHomescreenStep[];\n subtitle: string;\n}\n\n/** Header plus exactly one of the three tiers: install, steps, or copy-link. */\nconst InstallPanel = ({\n appIconUrl,\n detection,\n heading,\n messages,\n nativeInstall,\n onInstall,\n steps,\n subtitle,\n}: InstallPanelProps) => (\n <>\n \n {appIconUrl && (\n // biome-ignore lint/performance/noImgElement: registry items must run outside Next\n // eslint-disable-next-line next/no-img-element -- caller-supplied URL, and this file ships without a framework\n \n )}\n