Skip to content

InstallPrompt

PWA install prompt component for Progressive Web Apps.

Basic Usage

from faststrap import InstallPrompt

InstallPrompt(
    title="Install Our App",
    description="Get the best experience by installing our app!",
    ios_text="Tap Share and choose Add to Home Screen.",
    android_text="Tap Install to add this app to your home screen.",
    delay=3000
)

API Reference

Parameter Type Default Description
title str "Install App" Prompt title
description str "Add this app to your home screen for the best experience." Prompt message
ios_text str iOS install instruction iOS-specific helper text
android_text str Android install instruction Android install button text
delay int 3000 Milliseconds before prompt appears
**kwargs Any - Additional HTML attributes

Example

InstallPrompt(
    title="Install FastApp",
    description="Install our app for offline access and faster performance!",
    ios_text="Tap Share then Add to Home Screen.",
    android_text="Install Now",
    delay=2000
)

See Also

Behavior Notes

  • Requires Bootstrap JavaScript because it uses Bootstrap Toast.
  • Designed for apps that already call add_pwa().
  • iOS does not expose the same install prompt event as Chromium browsers, so the component shows manual iOS instructions.
  • Android/Desktop waits for the browser beforeinstallprompt event before showing the install button.

API Reference

faststrap.components.feedback.install_prompt.InstallPrompt(title='Install App', description='Add this app to your home screen for the best experience.', ios_text="Tap the Share button below and select 'Add to Home Screen'.", android_text="Tap 'Install' to add to your home screen.", delay=3000, **kwargs)

A smart component that prompts users to install the PWA.

It uses client-side logic to: 1. Check if app is not in standalone mode 2. Detect platform (iOS vs Android/Desktop) 3. Show appropriate instructions via a Toast

Source code in src/faststrap/components/feedback/install_prompt.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@register(category="feedback", requires_js=True)
def InstallPrompt(
    title: str = "Install App",
    description: str = "Add this app to your home screen for the best experience.",
    ios_text: str = "Tap the Share button below and select 'Add to Home Screen'.",
    android_text: str = "Tap 'Install' to add to your home screen.",
    delay: int = 3000,
    **kwargs: Any,
) -> Div:
    """
    A smart component that prompts users to install the PWA.

    It uses client-side logic to:
    1. Check if app is not in standalone mode
    2. Detect platform (iOS vs Android/Desktop)
    3. Show appropriate instructions via a Toast
    """

    # Create the Toast content structure
    toast_id = "pwa-install-toast"

    # We use a custom ToastContainer logic here because we want it fixed
    # But we can leverage the existing Toast component structure

    # The actual UI is hidden initially and triggered by the script
    toast_html = Toast(
        Div(
            P(description, cls="mb-2"),
            # iOS Instruction (hidden by default, shown by JS)
            Div(
                Small(Icon("share"), cls="me-1"),
                Small(ios_text),
                cls="d-none ios-instruction text-body-secondary",
            ),
            # Android/Generic Install Button (hidden by default)
            Button(
                android_text,
                cls="btn btn-sm btn-primary w-100 mt-2 d-none android-instruction",
                id="pwa-install-btn",
            ),
        ),
        title=Div(Strong(title), cls="me-auto"),
        id=toast_id,
        autohide=False,  # We want it to stay until dismissed
        **kwargs,
    )

    # Wrapper with ID for targeting
    container = Div(
        ToastContainer(toast_html, position="bottom-center", cls="p-3 mb-5"),
        id="faststrap-pwa-prompt",
    )

    # Client-side Logic (extracted for cleaner formatting)
    js_logic = _INSTALL_SCRIPT_TEMPLATE.format(toast_id=toast_id, delay=delay)
    script = Script(js_logic)

    return Div(container, script)