### Quick Start Guide - Framework Setup

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Guides for setting up PWA Install in various frameworks including Vanilla JavaScript, React, Next.js, Vue, Angular, Svelte, and Web Components.

```APIDOC
## Quick Start Guide - Framework Setup

### Description
Instructions for integrating PWA Install into different JavaScript frameworks.

### Frameworks Covered
- **Vanilla JavaScript**
- **React 19+ (native support)**
- **React 18 and earlier (wrapper)**
- **Next.js 15**
- **Vue 3**
- **Angular**
- **Svelte**
- **Web Components (all frameworks)**

### Example Content (per framework)
- **Full Working Example**
- **TypeScript Configuration**
- **Event Handling Patterns**
- **Ref/Template Access**
```

--------------------------------

### Quick Start Guide - Additional Coverage

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Additional topics covered in the Quick Start Guide, including manual event handling, configuration patterns, minimal manifest setup, HTTPS requirement, and troubleshooting.

```APIDOC
## Quick Start Guide - Additional Coverage

### Description
Covers advanced usage patterns and essential setup requirements.

### Topics
- **Manual Event Handling**: For asynchronous mounting scenarios.
- **Configuration Patterns**: Best practices for setting up.
- **Minimal Manifest Setup**: Requirements for a basic manifest.
- **HTTPS Requirement**: Importance of using HTTPS.
- **Common Troubleshooting**: Solutions to frequent issues.
```

--------------------------------

### Configuration Pattern Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Demonstrates various configuration options for PWA Install. This example shows how to customize the appearance and behavior.

```javascript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.userTitle = 'Install My Awesome App';
pwaInstall.userBody = 'Install this app to use it offline and in the background.';
pwaInstall.userIcon = '/icons/icon.png';
pwaInstall.enableLogging = true;
pwaInstall.custom = {
  '--pwa-install-button-background': '#3498db',
  '--pwa-install-button-color': '#ffffff'
};

pwaInstall.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  window.deferredPrompt = e;
  console.log('Custom prompt shown');
});

pwaInstall.addEventListener('appinstalled', () => {
  console.log('App was installed');
  window.deferredPrompt = null;
});
```

--------------------------------

### Framework Integration Example (React)

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Shows how to integrate PWA Install with a React application. This example assumes you have a React project set up.

```javascript
import React, { useEffect, useState } from 'react';
import '@khmyznikov/pwa-install';

function App() {
  const [supportsPwa, setSupportsPwa] = useState(false);
  const [prompt, setPrompt] = useState(null);

  useEffect(() => {
    const handler = (e) => {
      e.preventDefault();
      setPrompt(e);
    };
    window.addEventListener('beforeinstallprompt', handler);

    return () => window.removeEventListener(' கbeforeinstallprompt', handler);
  }, []);

  const installPwa = () => {
    prompt.prompt();
  };

  useEffect(() => {
    if (prompt) {
      setSupportsPwa(true);
    }
  }, [prompt]);

  return (
    <div className="App">
      <p>Install PWA</p>
      {supportsPwa && (
        <button onClick={installPwa}>Install PWA</button>
      )}
    </div>
  );
}

export default App;
```

--------------------------------

### Error Recovery Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Shows how to handle potential errors during the PWA installation process. This example logs errors to the console.

```javascript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('appinstall', () => {
  console.log('App installed successfully!');
});

pwaInstall.addEventListener('appinstallerror', (e) => {
  console.error('App installation failed:', e.detail.error);
  // Provide user feedback about the error
});
```

--------------------------------

### Platform Detection Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Illustrates how to detect the user's platform for tailored PWA installation prompts. This is useful for providing platform-specific instructions.

```javascript
const pwaInstall = document.querySelector('pwa-install');

const isIos = () => {
  const userAgent = window.navigator.userAgent;
  return /iPad|iPhone|iPod/.test(userAgent) && !window.MSStream;
};

const isAndroid = () => {
  const userAgent = window.navigator.userAgent;
  return /Android/.test(userAgent);
};

if (isIos()) {
  pwaInstall.userTitle = 'Add to Home Screen';
  pwaInstall.userBody = 'Tap the share button and then Add to Home Screen.';
} else if (isAndroid()) {
  pwaInstall.userTitle = 'Add to Home Screen';
  pwaInstall.userBody = 'Tap the "Add to Home screen" button in the menu.';
} else {
  pwaInstall.userTitle = 'Install PWA';
  pwaInstall.userBody = 'Install this app to use it offline and in the background.';
}
```

--------------------------------

### Complete React Legacy Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

This snippet shows a full implementation of the PWA Install component in a React application using the legacy export. It includes state management for installation status and event handlers for user interaction.

```typescript
import { useRef, useState } from 'react';
import PWAInstall from '@khmyznikov/pwa-install/react-legacy';
import type { PWAInstallElement } from '@khmyznikov/pwa-install';

function App() {
  const pwaInstallRef = useRef<PWAInstallElement>(null);
  const [isInstalled, setIsInstalled] = useState(false);

  return (
    <div className="app">
      <PWAInstall
        ref={pwaInstallRef}
        manifestUrl="/manifest.json"
        name="My PWA"
        description="A progressive web app"
        installDescription="Install our app for the best experience"
        useLocalStorage
        onPwaInstallSuccessEvent={() => setIsInstalled(true)}
        onPwaUserChoiceResultEvent={(e) => {
          console.log('User choice:', (e as CustomEvent).detail.message);
        }}
      />

      {isInstalled && <p>App installed successfully!</p>}

      <button onClick={() => pwaInstallRef.current?.showDialog(true)}>
        Show Install Dialog
      </button>
    </div>
  );
}

export default App;

```

--------------------------------

### install()

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Triggers the application installation process. This method behaves differently based on the platform: on Apple devices, it displays instructions on how to install; on Chrome/Android, it invokes the native installation prompt.

```APIDOC
## install()

### Description
Triggers app installation. On Apple platforms, it shows installation instructions; on Chrome/Android, it calls the native install prompt.

### Method
`install()`

### Parameters
None

### Returns
`void`

### Example
```javascript
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.install();
```
```

--------------------------------

### Language Switching Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Demonstrates how to dynamically switch the language of the PWA Install prompts. This requires providing translations for different languages.

```javascript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.language = 'es'; // Set language to Spanish

pwaInstall.translations = {
  'en': {
    'install': 'Install',
    'cancel': 'Cancel'
  },
  'es': {
    'install': 'Instalar',
    'cancel': 'Cancelar'
  }
};

// Later, to switch back to English:
pwaInstall.language = 'en';
```

--------------------------------

### Basic HTML Usage Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Demonstrates the fundamental HTML structure required for PWA installation prompts. Ensure this is included in your application's HTML.

```html
<link rel="manifest" href="/manifest.json">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="apple-mobile-web-app-title" content="PWA Install">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/icons/favicon-16x16.png">
<link rel="mask-icon" href="/icons/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">
```

--------------------------------

### Trigger Installation

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/README.md

The install method initiates the platform-specific installation process.

```typescript
// Trigger installation (platform-specific)
pwaInstall.install();
```

--------------------------------

### Install @lit/react for React 18 and Earlier

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Install the legacy React wrapper for older React versions. This is a prerequisite for using the React 18 and earlier example.

```bash
npm install @lit/react
```

--------------------------------

### Installation

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

Installs the necessary packages for PWAInstall React legacy integration, including the pwa-install package, @lit/react, and react.

```bash
npm install @khmyznikov/pwa-install @lit/react react
```

--------------------------------

### IRelatedApp Usage Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/types.md

Demonstrates how to retrieve and iterate over installed related applications, logging their platform and ID.

```typescript
const apps = await pwaInstall.getInstalledRelatedApps();
apps.forEach(app => {
  console.log(`${app.platform}: ${app.id}`);
  // play: com.example.app
  // itunes: 123456789
});
```

--------------------------------

### Basic JavaScript Usage Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Illustrates the basic JavaScript initialization for PWA installation. This code should be included in your application's JavaScript files.

```javascript
import 'https://cdn.jsdelivr.net/npm/@khmyznikov/pwa-install@1.0.0/dist/pwa-install.min.js';

const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the default prompt
  e.preventDefault();
  // Show your custom banner or prompt
  console.log('👍', 'beforeinstallprompt Event fired');
  // Stash the event so it can be triggered later.
  window.deferredPrompt = e;
  // Update UI etc.
});

pwaInstall.addEventListener('appinstalled', () => {
  // Hide the install button
  console.log('👍', 'appinstalled Event fired');
  window.deferredPrompt = null;
});
```

--------------------------------

### TypeScript Integration Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Illustrates the usage of PWA Install with TypeScript, including type definitions for better code safety and autocompletion.

```typescript
import 'https://cdn.jsdelivr.net/npm/@khmyznikov/pwa-install@1.0.0/dist/pwa-install.min.js';
import { PwaInstall } from '@khmyznikov/pwa-install';

const pwaInstallElement = document.querySelector<PwaInstall>('pwa-install');

if (pwaInstallElement) {
  pwaInstallElement.userTitle = 'Install My App';
  pwaInstallElement.addEventListener('beforeinstallprompt', (e: BeforeInstallPromptEvent) => {
    e.preventDefault();
    window.deferredPrompt = e;
    console.log('Before install prompt fired');
  });

  pwaInstallElement.addEventListener('appinstalled', () => {
    console.log('App was installed');
    window.deferredPrompt = null;
  });
}
```

--------------------------------

### Show Install Dialog

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Use `showDialog()` to display the install prompt. Setting the optional `forced` parameter to `true` will override normal availability checks and force the dialog to appear.

```typescript
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.showDialog(true);
```

--------------------------------

### Manual Event Handling for PWA Install

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Capture the 'beforeinstallprompt' event and manually trigger the PWA install dialog. Useful for custom control over the install experience.

```javascript
let promptEvent = null;

// Capture event early
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  e.stopImmediatePropagation();
  promptEvent = e;
});

// When component is ready, pass the event
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.externalPromptEvent = promptEvent;
pwaInstall.manualChrome = true;
pwaInstall.showDialog(true);
```

--------------------------------

### Trigger App Installation

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Use the `install()` method to trigger the app installation process. This method behaves differently across platforms, showing installation instructions on Apple devices and invoking the native prompt on Chrome/Android.

```typescript
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.install();
```

--------------------------------

### Handle Deferred Installation Prompt

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/configuration.md

Manually capture the 'beforeinstallprompt' event to control when the installation dialog is shown. Mount the component and pass the captured event, then trigger the dialog on user interaction.

```typescript
let promptEvent = null;

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  e.stopImmediatePropagation();
  promptEvent = e;
});

// Mount component later and pass event
const pwaInstall = document.createElement('pwa-install');
pwaInstall.externalPromptEvent = promptEvent;
pwaInstall.manualChrome = true;
document.body.appendChild(pwaInstall);

// Show on user action
button.addEventListener('click', () => {
  pwaInstall.showDialog(true);
});
```

--------------------------------

### React 18 and Earlier PWA Install Component

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Utilize the legacy React wrapper for PWA Install in React versions 18 and earlier. This example shows how to control the install dialog programmatically.

```typescript
import PWAInstall from '@khmyznikov/pwa-install/react-legacy';
import { useRef } from 'react';

function App() {
  const pwaRef = useRef(null);

  return (
    <>
      <PWAInstall
        ref={pwaRef}
        manifestUrl="/manifest.json"
        name="My App"
        description="My awesome app"
        useLocalStorage
        onPwaInstallSuccessEvent={() => console.log('Installed!')}
      />
      <button onClick={() => pwaRef.current?.showDialog(true)}>
        Show Install Dialog
      </button>
    </>
  );
}

export default App;
```

--------------------------------

### Check for Installed Related Apps

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/errors.md

This example shows how to use the `getInstalledRelatedApps()` method and handle cases where the API is unavailable or no related apps are installed. It logs a message if no apps are found.

```javascript
const pwaInstall = document.querySelector('pwa-install');
const apps = await pwaInstall.getInstalledRelatedApps();

if (apps.length === 0) {
  console.log('No installed related apps (or API unavailable)');
} else {
  apps.forEach(app => console.log(app.platform, app.id));
}
```

--------------------------------

### Desktop-Only PWA Install Configuration

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/platform-support.md

Configure settings for desktop browsers when the pwa-install component is available. This example disables screenshots for desktop users.

```typescript
pwaInstall.addEventListener('pwa-install-available-event', () => {
  if (!pwaInstall.isAppleMobilePlatform && !pwaInstall.isAndroid) {
    // Desktop browser
    pwaInstall.disableScreenshots = true; // Desktop users don't need these
  }
});
```

--------------------------------

### Install PWA Component

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

This snippet demonstrates how to programmatically trigger the PWA installation process using the component's install method.

```html
<script type="text/javascript">
  var pwaInstall = document.getElementsByTagName('pwa-install')[0];

  pwaInstall.install();
</script>
```

--------------------------------

### File Structure Overview

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

This code block displays the directory structure of the generated documentation. It helps users understand where to find specific information, such as the quick start guide, API references, and configuration details.

```bash
output/
├── README.md                    # Start here - index and quick navigation
├── OVERVIEW.md                  # This file
├── quick-start.md              # Setup for all frameworks (8.2 KB)
├── types.md                    # All TypeScript types (8.1 KB)
├── configuration.md            # Config options and patterns (8.1 KB)
├── localization.md             # 32 language support (9.0 KB)
├── errors.md                   # Error handling guide (8.7 KB)
├── modules.md                  # Module graph (10 KB)
├── platform-support.md         # Browser compatibility (9.7 KB)
└── api-reference/
    ├── pwa-install-element.md  # Main component (7.9 KB)
    ├── utils.md                # Utility class (8.1 KB)
    ├── pwa-gallery-element.md  # Gallery component (2.7 KB)
    ├── pwa-bottom-sheet-element.md # Mobile dialog (3.7 KB)
    └── react-legacy.md         # React wrapper (6.3 KB)
```

--------------------------------

### Vue 3 PWA Install with TypeScript and Dialog Control

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Use PWA Install in Vue 3 with TypeScript, including type safety for the element reference. This example demonstrates how to programmatically show the install dialog.

```vue
<template>
  <pwa-install
    ref="pwaInstallRef"
    manifest-url="/manifest.json"
    name="My App"
  ></pwa-install>
  <button @click="showDialog">Show Install</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import '@khmyznikov/pwa-install';
import type { PWAInstallElement } from '@khmyznikov/pwa-install';

const pwaInstallRef = ref<PWAInstallElement>();

const showDialog = () => {
  pwaInstallRef.value?.showDialog(true);
};
</script>
```

--------------------------------

### Install PWA Install Component

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

Install the component using npm. This is the primary method for adding the library to your project.

```bash
npm i @khmyznikov/pwa-install
```

--------------------------------

### Basic Usage of PWA Install Component

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

Use the custom element `<pwa-install></pwa-install>` in your HTML to render the PWA installation prompt. Ensure the component has been imported.

```html
<pwa-install></pwa-install>
```

--------------------------------

### Install pwa-install Package

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/README.md

Install the pwa-install package using npm. This is the first step to integrate the component into your project.

```bash
npm install @khmyznikov/pwa-install
```

--------------------------------

### Custom Install Description

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Set a custom message to display to the user when prompting for PWA installation.

```html
<pwa-install
  install-description="Download our app for the best experience!"
></pwa-install>
```

--------------------------------

### Advanced Scenario: Deferred Events

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/OVERVIEW.md

Demonstrates handling deferred installation prompts, allowing users to install the PWA at a more convenient time. This is useful for complex user flows.

```javascript
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferredPrompt = e;
  // Show your custom install button
  document.getElementById('install-button').style.display = 'block';
});

document.getElementById('install-button').addEventListener('click', async () => {
  if (deferredPrompt) {
    deferredPrompt.prompt();
    const { outcome } = await deferredPrompt.userChoice;
    console.log(`User response to the install prompt: ${outcome}`);
    if (outcome === 'accepted') {
      console.log('User accepted the A2HS prompt');
    } else {
      console.log('User dismissed the A2HS prompt');
    }
    deferredPrompt = null;
    // Hide the install button
    document.getElementById('install-button').style.display = 'none';
  }
});

window.addEventListener('appinstalled', () => {
  console.log('PWA was installed');
  deferredPrompt = null;
});
```

--------------------------------

### Show Dialog Based on Platform

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Conditionally display installation instructions or trigger automatic installation based on the user's platform (iOS or Android).

```javascript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('pwa-install-available-event', () => {
  if (pwaInstall.isAppleMobilePlatform) {
    // Show instructions for iOS
    pwaInstall.manualApple = true;
  } else if (pwaInstall.isAndroid) {
    // Auto-show for Android
    pwaInstall.manualChrome = false;
  }
});
```

--------------------------------

### Handling BeforeInstallPrompt Event

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/types.md

Demonstrates how to capture the beforeinstallprompt event and store it for later use, typically for triggering the PWA installation.

```typescript
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  window.promptEvent = e;
});

// Later, pass to component
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.externalPromptEvent = window.promptEvent;
```

--------------------------------

### showDialog(forced?)

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Displays the install dialog. If the `forced` parameter is set to `true`, it also sets `isInstallAvailable` to `true`, ensuring the dialog is shown even if installation is not typically available.

```APIDOC
## showDialog(forced?)

### Description
Shows the install dialog. If `forced` is true, it also sets `isInstallAvailable` to true to display the dialog even if install is not normally available.

### Method
`showDialog(forced?: boolean)`

### Parameters
#### Path Parameters
- **forced** (boolean) - Optional - Force dialog visibility and set install available

### Returns
`void`

### Example
```javascript
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.showDialog(true);
```
```

--------------------------------

### Dispatch PWA Install How To Event

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/utils.md

Dispatches the `pwa-install-how-to-event` on the provided element.

```typescript
static eventInstallHowTo(_element: Element): void
```

--------------------------------

### Handle PWA Install Events

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

Use event handlers like `onPwaInstallSuccessEvent` and `onPwaUserChoiceResultEvent` to react to installation outcomes. The event details are available in `e.detail.message`.

```typescript
import PWAInstall from '@khmyznikov/pwa-install/react-legacy';

function App() {
  const handleInstallSuccess = (e: Event) => {
    const customEvent = e as CustomEvent;
    console.log(customEvent.detail.message);
  };

  const handleUserChoice = (e: Event) => {
    const customEvent = e as CustomEvent;
    console.log('User choice:', customEvent.detail.message); // 'accepted' or 'dismissed'
  };

  return (
    <PWAInstall
      manifestUrl="/manifest.json"
      onPwaInstallSuccessEvent={handleInstallSuccess}
      onPwaUserChoiceResultEvent={handleUserChoice}
    />
  );
}

export default App;

```

--------------------------------

### Configure and Use PWAGalleryElement

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-gallery-element.md

Example of how to import, query, configure properties, and navigate the PWAGalleryElement.

```typescript
import { ManifestScreenshot } from '@khmyznikov/pwa-install';

const gallery = document.querySelector('pwa-gallery') as PWAGalleryElement;

const screenshots: ManifestScreenshot[] = [
  { src: '/screenshot1.png', form_factor: 'narrow' },
  { src: '/screenshot2.png', form_factor: 'narrow' },
];

gallery.screenshots = screenshots;
gallery.theme = 'apple_mobile';
gallery.rtl = false;

// Navigate
gallery.scrollToNextPage();
gallery.scrollToPrevPage();
```

--------------------------------

### iOS/iPadOS Configuration

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/platform-support.md

Configure the pwa-install component for iOS and iPadOS devices. This setup is used to display installation instructions or native UI prompts.

```html
<pwa-install
  name="My App"
  icon="/icon-180x180.png"
  description="Install instructions will appear"
></pwa-install>
```

--------------------------------

### Ref Access Methods

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

You can access the underlying PWAInstallElement using a ref to programmatically control the PWA installation process and retrieve installation status.

```APIDOC
## Ref Access

### Description
Use a ref to access the underlying `PWAInstallElement` and call its methods.

### Methods
- `showDialog(show: boolean)`: Programmatically shows or hides the PWA installation dialog.
- `install()`: Initiates the PWA installation process.
- `getInstalledRelatedApps()`: Returns a Promise that resolves with an array of installed related apps.

### Example Usage
```typescript
import { useRef } from 'react';
import PWAInstall from '@khmyznikov/pwa-install/react-legacy';

const pwaInstallRef = useRef(null);

// To show the dialog:
pwaInstallRef.current?.showDialog(true);

// To initiate installation:
pwaInstallRef.current?.install();

// To get installed apps:
const apps = await pwaInstallRef.current?.getInstalledRelatedApps();
```
```

--------------------------------

### PWA Install Component with All Supported Parameters

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

Customize the PWA install prompt's behavior and appearance using a comprehensive set of HTML attributes. Boolean attributes should be omitted to be treated as 'false'.

```html
<pwa-install
  manual-apple
  manual-chrome
  disable-chrome
  disable-close
  use-local-storage

  install-description="Custom call to install text"
  disable-install-description
  disable-screenshots
  disable-screenshots-apple
  disable-screenshots-chrome
  manual-how-to

  disable-android-fallback

  manifest-url="/manifest.json"
  name="PWA"
  description="Progressive web application"
  icon="/icon.png">
</pwa-install>
```

--------------------------------

### Handle User Choice for Installation

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/errors.md

Listen for the 'pwa-user-choice-result-event' to detect whether the user accepted or dismissed the installation prompt. The 'dismissed' detail message indicates the user canceled the process.

```typescript
pwaInstall.addEventListener('pwa-user-choice-result-event', (e) => {
  const choice = (e as CustomEvent).detail.message;
  
  if (choice === 'dismissed') {
    console.log('User dismissed installation');
    // Dialog hides automatically
  } else if (choice === 'accepted') {
    console.log('User accepted installation');
  }
});
```

--------------------------------

### Usage Example for PWABottomSheetElement

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-bottom-sheet-element.md

Demonstrates how to instantiate and configure the PWABottomSheetElement by setting its properties and event handlers.

```javascript
const bottomSheet = document.querySelector('pwa-bottom-sheet');

bottomSheet.props = {
  name: 'My App',
  description: 'An awesome app',
  icon: '/icon-192x192.png'
};

bottomSheet.install = {
  handleEvent: () => {
    console.log('Install clicked');
  }
};

bottomSheet.hideDialog = () => {
  console.log('User dismissed');
};

bottomSheet.fallback = false;
bottomSheet.disableClose = false;
```

--------------------------------

### Listen for PWA Install Success Event

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/README.md

Add an event listener to capture successful PWA installations. The event detail contains a success message.

```typescript
pwaInstall.addEventListener('pwa-install-success-event', (e) => {
  console.log(e.detail.message); // 'App install success'
});
```

--------------------------------

### Listen to PWA Install Events and Check Platform

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/errors.md

Attach event listeners to the pwa-install element to debug the installation flow. Also, log platform detection properties to verify component behavior.

```typescript
// Listen to all events to debug flow
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('pwa-install-available-event', () => {
  console.log('Install available');
});

pwaInstall.addEventListener('pwa-install-success-event', () => {
  console.log('Install success');
});

pwaInstall.addEventListener('pwa-install-fail-event', () => {
  console.log('Install failed');
});

pwaInstall.addEventListener('pwa-user-choice-result-event', (e) => {
  console.log('User choice:', (e as CustomEvent).detail.message);
});

pwaInstall.addEventListener('pwa-install-how-to-event', () => {
  console.log('How-to shown (Apple)');
});

pwaInstall.addEventListener('pwa-install-gallery-event', () => {
  console.log('Gallery shown');
});

// Check platform detection
console.log({
  isAppleMobile: pwaInstall.isAppleMobilePlatform,
  isAppleDesktop: pwaInstall.isAppleDesktopPlatform,
  isAndroid: pwaInstall.isAndroid,
  isStandalone: pwaInstall.isUnderStandaloneMode,
  installAvailable: pwaInstall.isInstallAvailable,
  isHidden: pwaInstall.isDialogHidden
});
```

--------------------------------

### ManifestScreenshot Usage Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/types.md

Provides an example of how to define an array of ManifestScreenshot objects for use in a web app manifest.

```typescript
const screenshots: ManifestScreenshot[] = [
  {
    src: '/screenshot1.png',
    sizes: '540x720',
    form_factor: 'narrow',
    platform: 'ios',
    label: 'Home screen'
  },
  {
    src: '/screenshot2.png',
    sizes: '1024x768',
    form_factor: 'wide',
    platform: 'windows',
    label: 'Desktop view'
  }
];
```

--------------------------------

### Hide Install Dialog

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Call `hideDialog()` to dismiss the install prompt and record the user's choice as dismissed. This prevents the prompt from reappearing.

```typescript
const pwaInstall = document.querySelector('pwa-install');
pwaInstall.hideDialog();
```

--------------------------------

### Configure PWA Install Component via HTML

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/README.md

Use this snippet to configure the pwa-install component directly in your HTML. Set attributes for manifest URL, app name, description, icon, and installation prompts.

```html
<pwa-install
  manifest-url="/manifest.json"
  name="My App"
  description="An awesome PWA"
  icon="/icons/icon-192x192.png"
  install-description="Install for the best experience"
  use-local-storage
  disable-android-fallback="false"
  styles='{"--tint-color": "#6366f1"}'
></pwa-install>
```

--------------------------------

### PWA Install Element HTML Attributes

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Configure the PWA Install Element using HTML attributes. Properties like manifestUrl, installDescription, and styles can be set directly.

```html
<pwa-install
  manifest-url="/app.manifest.json"
  install-description="Get the app!"
  disable-install-description="false"
  manual-chrome
  use-local-storage
  styles='{"--tint-color": "#6366f1"}'
></pwa-install>
```

--------------------------------

### Example Usage of Event Dispatching

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/utils.md

Demonstrates how to dispatch a success event and listen for it, logging the detail message.

```typescript
const element = document.querySelector('pwa-install');
Utils.eventInstalledSuccess(element);

element.addEventListener('pwa-install-success-event', (e) => {
  console.log(e.detail.message);
});
```

--------------------------------

### Capture and Use beforeinstallprompt Event

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

This snippet shows how to capture the 'beforeinstallprompt' event and pass it to the PWA Install component's externalPromptEvent property for deferred installation. This is useful for targeting Chromium browsers and postponing component mounting.

```javascript
// capture event asap, better right in index.html script tag
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  e.stopPropagation();
  e.stopImmediatePropagation();

  // save it somewhere
  window.promptEvent = e;
});

// later render the component on demand and pass event
document.getElementById("pwa-install").externalPromptEvent = window.promptEvent;
```

--------------------------------

### Clone the Repository

Source: https://github.com/khmyznikov/pwa-install/blob/main/CONTRIBUTING.md

Clone the project repository to your local machine to start making changes.

```bash
git clone https://github.com/github-username/pwa-install.git
```

--------------------------------

### Get Installed Related Apps

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/README.md

Retrieve a list of installed related applications. This functionality is specific to Chromium-based browsers.

```typescript
// Get installed related apps (Chromium only)
const apps = await pwaInstall.getInstalledRelatedApps();
```

--------------------------------

### Full Vanilla JavaScript Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

A complete HTML file demonstrating the integration of pwa-install with vanilla JavaScript, including configuration, event listeners, and manual dialog display.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="manifest" href="/manifest.json">
  <title>My PWA</title>
</head>
<body>
  <pwa-install></pwa-install>

  <button id="show-install">Show Install Dialog</button>

  <script type="module">
    import '@khmyznikov/pwa-install';

    const pwaInstall = document.querySelector('pwa-install');

    // Configure
    pwaInstall.manifestUrl = '/manifest.json';
    pwaInstall.name = 'My App';
    pwaInstall.description = 'My awesome PWA';
    pwaInstall.useLocalStorage = true;

    // Listen for events
    pwaInstall.addEventListener('pwa-install-success-event', () => {
      console.log('App installed successfully!');
    });

    pwaInstall.addEventListener('pwa-user-choice-result-event', (e) => {
      console.log('User choice:', e.detail.message);
    });

    // Show dialog on button click
    document.getElementById('show-install').addEventListener('click', () => {
      pwaInstall.showDialog(true);
    });
  </script>
</body>
</html>
```

--------------------------------

### Control PWA Install Dialog and Events

Source: https://github.com/khmyznikov/pwa-install/blob/main/docs/index.html

Manages the PWA Install component's dialog visibility, attributes, and listens for various installation-related events. Use this to dynamically update the component's behavior and log outcomes.

```javascript
var pwaInstall = document.getElementById("pwa-install");
document.getElementById('events-area').value = "";
const logMessage = (message) => {
  console.log(message);
  document.getElementById('events-area').value+=\`: ${message}\r\n	`;
}
const getRelated = () => {
  pwaInstall.getInstalledRelatedApps().then( (result) => {
    logMessage(result.toString() || 'None');
  } )
}
const forceStyle = (style) => {
  pwaInstall.isAppleMobilePlatform = false;
  pwaInstall.isAppleDesktopPlatform = false;
  pwaInstall.isAndroidFallback = false;
  pwaInstall.isLiquidGlassSupported = false;
  pwaInstall._pageReflection = false;
  pwaInstall.isApple26Plus = false;
  switch (style) {
    case 'apple-mobile':
      pwaInstall.isAppleMobilePlatform = true;
      break;
    case 'apple-desktop':
      pwaInstall.isAppleDesktopPlatform = true;
      break;
    case 'chrome':
      break;
    case 'fallback':
      pwaInstall.isAndroidFallback = true;
      break;
    case 'liquid-glass-desktop':
      pwaInstall.isApple26Plus = true;
      pwaInstall.isAppleDesktopPlatform = true;
      break;
    case 'liquid-glass-mobile':
      pwaInstall.isApple26Plus = true;
      pwaInstall.isAppleMobilePlatform = true;
      break;
  }
  pwaInstall.hideDialog();
  pwaInstall.showDialog();
}
const disableInstallDescription = (cb) => {
  cb.checked ? pwaInstall.setAttribute('disable-install-description', true) : pwaInstall.removeAttribute('disable-install-description');
}
const disableScreenshots = (cb) => {
  cb.checked ? pwaInstall.setAttribute('disable-screenshots', true) : pwaInstall.removeAttribute('disable-screenshots');
}
const disableScreenshotsPlatform = (cb, platform) => {
  cb.checked ? pwaInstall.setAttribute(\`disable-screenshots-${platform}\`, true) : pwaInstall.removeAttribute(\`disable-screenshots-${platform}\`);
}
const disableClose = (cb) => {
  cb.checked ? pwaInstall.setAttribute('disable-close', true) : pwaInstall.removeAttribute('disable-close');
}
const manualHowTo = (cb) => {
  cb.checked ? pwaInstall.setAttribute('manual-how-to', true) : pwaInstall.removeAttribute('manual-how-to');
  pwaInstall._galleryRequested = false;
}
const setAttr = (attr, value) => {
  value? pwaInstall.setAttribute(attr, value) : pwaInstall.removeAttribute(attr);
  pwaInstall._init();
}
const setStyles = (color) => {
  if (color) {
    pwaInstall.setAttribute('styles', JSON.stringify({ '--tint-color': color }));
  } else {
    pwaInstall.removeAttribute('styles');
    document.getElementById('tint-color-picker').value = '';
  }
  pwaInstall.hideDialog();
  pwaInstall.showDialog();
}
pwaInstall.addEventListener('pwa-install-success-event', (event) => {
  logMessage(event.detail.message)
});
pwaInstall.addEventListener('pwa-install-fail-event', (event) => {
  logMessage(event.detail.message)
});
pwaInstall.addEventListener('pwa-user-choice-result-event', (event) => {
  logMessage(event.detail.message)
});
pwaInstall.addEventListener('pwa-install-available-event', (event) => {
  logMessage(event.detail.message)
});
pwaInstall.addEventListener('pwa-install-how-to-event', (event) => {
  logMessage(event.detail.message)
});
pwaInstall.addEventListener('pwa-install-gallery-event', (event) => {
  logMessage(event.detail.message)
});
```

--------------------------------

### Dispatch PWA Install Available Event

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/utils.md

Dispatches the `pwa-install-available-event` on the specified element.

```typescript
static eventInstallAvailable(_element: Element): void
```

--------------------------------

### PWAInstallElement Properties

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

The PWAInstallElement exposes various input properties (attributes) that can be set to customize the appearance and behavior of the installation prompt, and read-only public properties that provide information about the current installation status and platform.

```APIDOC
## PWAInstallElement Properties

### Input Properties (Attributes)

| Property | Type | Default | Description |
|---|---|---|---|
| `manifestUrl` | `string` | `/manifest.json` | URL to the Web App Manifest file |
| `icon` | `string` | `''` | URL to the app icon (overrides manifest) |
| `name` | `string` | `''` | App display name (overrides manifest short_name) |
| `description` | `string` | `''` | App description (overrides manifest description) |
| `installDescription` | `string` | `''` | Custom install call-to-action text |
| `disableDescription` | `boolean` | `false` | Hide the default install description |
| `disableScreenshots` | `boolean` | `false` | Hide all screenshots |
| `disableScreenshotsApple` | `boolean` | `false` | Hide screenshots on Apple platforms only |
| `disableScreenshotsChrome` | `boolean` | `false` | Hide screenshots on Chrome only |
| `manualApple` | `boolean` | `false` | Require manual `showDialog()` call on Apple platforms |
| `manualChrome` | `boolean` | `false` | Require manual `showDialog()` call on Chrome |
| `manualHowTo` | `boolean` | `false` | Show installation instructions immediately (Apple only) |
| `disableChrome` | `boolean` | `false` | Disable custom Chrome install logic; use browser native |
| `disableClose` | `boolean` | `false` | Hide the close button |
| `disableAndroidFallback` | `boolean` | `false` | Disable install instructions for non-Chrome Android browsers |
| `useLocalStorage` | `boolean` | `false` | Persist user's "ignore" choice in localStorage instead of sessionStorage |
| `styles` | `Record<string, string>` | `{}` | Custom CSS variables for styling (Apple template only; supports `--tint-color`) |
| `externalPromptEvent` | `BeforeInstallPromptEvent | null` | `null` | Manually provide a captured `beforeinstallprompt` event for async mounting |

### Read-Only Public Properties

| Property | Type | Description |
|---|---|---|
| `platforms` | `BeforeInstallPromptEvent['platforms']` | Array of install platform strings from beforeinstallprompt |
| `userChoiceResult` | `string` | User's choice: `'accepted'`, `'dismissed'`, or empty string |
| `isDialogHidden` | `boolean` | Whether the install dialog is currently hidden |
| `isInstallAvailable` | `boolean` | Whether installation is available on this platform |
| `isAppleMobilePlatform` | `boolean` | Detected iOS or iPadOS |
| `isAppleDesktopPlatform` | `boolean` | Detected macOS with Safari 17+ |
| `isApple26Plus` | `boolean` | Detected macOS 26+ (Sonoma) or iOS/iPadOS 26+ for native UI |
| `isAndroidFallback` | `boolean` | Using fallback instructions for non-Chrome Android browsers |
| `isAndroid` | `boolean` | Detected Android platform |
| `isUnderStandaloneMode` | `boolean` | App is already installed and running in standalone mode |
| `isRelatedAppsInstalled` | `boolean` | Native app from manifest.related_applications is installed |
```

--------------------------------

### Listening to PWA Install Success and User Choice Events

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

Attach event listeners to the pwa-install element to capture installation success and user choice results. The event detail object contains a message property.

```typescript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('pwa-install-success-event', (event) => {
  console.log('App installed:', event.detail.message);
});

pwaInstall.addEventListener('pwa-user-choice-result-event', (event) => {
  console.log('User choice:', event.detail.message); // 'accepted' or 'dismissed'
});
```

--------------------------------

### Import PWAInstall Types

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/modules.md

Imports specific type definitions for PWA installation properties, attributes, and elements from the '@khmyznikov/pwa-install' package.

```typescript
import type { PWAInstallProps } from '@khmyznikov/pwa-install';
import type { PWAInstallAttributes } from '@khmyznikov/pwa-install';
import type { PWAInstallElement } from '@khmyznikov/pwa-install';
```

--------------------------------

### Vue 3 PWA Install Component

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Integrate the PWA Install web component directly into Vue 3 templates. Ensure the component is imported in the script setup.

```vue
<template>
  <pwa-install
    manifest-url="/manifest.json"
    name="My App"
    description="My awesome app"
    use-local-storage
  ></pwa-install>
</template>

<script setup>
import '@khmyznikov/pwa-install';
</script>
```

--------------------------------

### Manifest Class Usage Example

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/types.md

Shows how to instantiate and populate the Manifest class with application details like name, description, and icons.

```typescript
const manifest = new Manifest();
manifest.name = 'My PWA';
manifest.description = 'An awesome app';
manifest.icons = [
  { src: '/icon-192.png', sizes: '192x192' },
  { src: '/icon-512.png', sizes: '512x512' }
];
```

--------------------------------

### Get Installed Related Apps

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/pwa-install-element.md

The `getInstalledRelatedApps()` method queries for installed related applications defined in the manifest. This functionality is specific to Chromium-based browsers and will return an empty array on iOS. Errors during the query are silently caught and result in an empty array.

```typescript
const pwaInstall = document.querySelector('pwa-install');
const installedApps = await pwaInstall.getInstalledRelatedApps();
console.log(installedApps); // [{id: '...', platform: '...', url: '...'}]
```

--------------------------------

### Example Usage of Fetch and Process Manifest

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/utils.md

Shows how to call `fetchAndProcessManifest` with custom parameters and log the resulting manifest name and icon URL.

```typescript
const result = await Utils.fetchAndProcessManifest(
  '/manifest.json',
  '/icon-192.png',
  'My App',
  'An awesome app'
);

console.log(result._manifest.name);
console.log(result.icon);
```

--------------------------------

### Access PWAInstallElement Methods via Ref

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

Utilize `useRef` to get a reference to the `PWAInstallElement` and call methods such as `showDialog`, `install`, and `getInstalledRelatedApps`.

```typescript
import { useRef } from 'react';
import PWAInstall from '@khmyznikov/pwa-install/react-legacy';
import type { PWAInstallElement } from '@khmyznikov/pwa-install';

function App() {
  const pwaInstallRef = useRef<PWAInstallElement>(null);

  const handleShowDialog = () => {
    pwaInstallRef.current?.showDialog(true);
  };

  const handleInstall = () => {
    pwaInstallRef.current?.install();
  };

  const handleGetApps = async () => {
    const apps = await pwaInstallRef.current?.getInstalledRelatedApps();
    console.log(apps);
  };

  return (
    <>
      <PWAInstall ref={pwaInstallRef} />
      <button onClick={handleShowDialog}>Show Dialog</button>
      <button onClick={handleInstall}>Install</button>
      <button onClick={handleGetApps}>Get Installed Apps</button>
    </>
  );
}

export default App;

```

--------------------------------

### React 19+ Native Web Component Usage

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/api-reference/react-legacy.md

This example demonstrates how to use the PWA Install component directly as a native Web Component in React 19 and later, leveraging built-in JSX support for custom elements.

```typescript
import '@khmyznikov/pwa-install';

export function App() {
  return <pwa-install manifest-url="/manifest.json" name="My App" />;
}

```

--------------------------------

### Log PWA Install Availability Status

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/quick-start.md

Log the current installation availability status and related properties of the PWA Install component. This helps diagnose why the installation dialog might not be showing.

```javascript
console.log({
  isInstallAvailable: pwaInstall.isInstallAvailable,
  isDialogHidden: pwaInstall.isDialogHidden,
  isUnderStandaloneMode: pwaInstall.isUnderStandaloneMode,
  isAppleMobile: pwaInstall.isAppleMobilePlatform,
  isAndroid: pwaInstall.isAndroid
});
```

--------------------------------

### Handle BeforeInstallPromptEvent Availability

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/errors.md

Listen for the 'pwa-install-available-event' to determine if the native install prompt is available or if a fallback is needed. This is useful for browsers that do not support BeforeInstallPromptEvent.

```typescript
const pwaInstall = document.querySelector('pwa-install');

pwaInstall.addEventListener('pwa-install-available-event', () => {
  if (pwaInstall.isAndroidFallback) {
    console.log('Showing fallback installation instructions');
  } else {
    console.log('Native install prompt available');
  }
});
```

--------------------------------

### Check PWA Install Availability Status

Source: https://github.com/khmyznikov/pwa-install/blob/main/README.md

Access the 'isInstallAvailable' read-only property of the PWA Install component to determine if the PWA can be installed. This is useful for conditionally showing or hiding installation prompts.

```javascript
var pwaInstall = document.getElementsByTagName('pwa-install')[0];

console.log(pwaInstall.isUnderStandaloneMode);
```

--------------------------------

### PWAInstall Element HTML Usage

Source: https://github.com/khmyznikov/pwa-install/blob/main/_autodocs/types.md

Example of how to use the <pwa-install> custom element in HTML, demonstrating the usage of various attributes like manifest-url, name, description, icon, and control flags.

```html
<pwa-install
  manifest-url="/manifest.json"
  name="My App"
  description="My awesome app"
  icon="/icon-192.png"
  manual-chrome="true"
  disable-install-description="false"
></pwa-install>
```