JavaScript API

The Filament WebPush package provides global JavaScript functions that allow you to integrate push notifications anywhere in your application, especially with Alpine.js.

Available Functions

registerWebPush()

Prompts the user to subscribe to push notifications. This function handles permission requests, service worker registration, and server communication.

Returns: Promise<{success: boolean, message: string}>

// Usage with Alpine.js
<button [@click](https://github.com/click)="registerWebPush().then(result => handleResult(result))">
    Subscribe to Notifications
</button>

unregisterWebPush()

Unsubscribes the user from push notifications and removes the subscription from the server.

Returns: Promise<{success: boolean, message: string}>

// Usage with Alpine.js
<button [@click](https://github.com/click)="unregisterWebPush().then(result => handleResult(result))">
    Unsubscribe
</button>

checkWebPushStatus()

Checks the current subscription status and browser support.

Returns: Promise<{supported: boolean, subscribed: boolean, permission: string, error?: string}>

// Usage with Alpine.js
<div
    x-data="{ status: null }"
    x-init="checkWebPushStatus().then(s => status = s)"
>
    <span x-show="status?.supported">Browser supports push notifications</span>
    <span x-show="status?.subscribed">Currently subscribed</span>
</div>

Full Component Example

<div
    x-data="{
        hasSubscription: false,
        loading: false,

        async enableWebPush() {
            if (this.loading) {
                return;
            }

            this.loading = true;
            await window.registerWebPush()
                .then(() => {
                    this.loading = false;
                    this.hasSubscription = true;
                    new FilamentNotification()
                        .title('{{ __('Notifications Enabled') }}')
                        .success()
                        .send()
                })
                .catch(() => {
                    this.loading = false;
                    new FilamentNotification()
                        .title('{{ __('Error') }}')
                        .body('{{ __('Failed to enable notifications') }}')
                        .danger()
                        .send()
                });
        },

        async disableWebPush() {
            if (this.loading) {
                return;
            }

            this.loading = true;
            await window.unregisterWebPush()
                .then(() => {
                    this.loading = false;
                    this.hasSubscription = false;
                    new FilamentNotification()
                        .title('{{ __('Notifications Disabled') }}')
                        .body('{{ __('You have successfully unsubscribed from notifications') }}')
                        .success()
                        .send()
                })
                .catch(() => {
                    this.loading = false;
                    new FilamentNotification()
                        .title('{{ __('Error') }}')
                        .body('{{ __('Failed to disable notifications') }}')
                        .danger()
                        .send()
                });
        },

        async init() {
            await window.checkWebPushStatus()
                .then((result) => {
                    if (result.supported === false) {
                        new FilamentNotification()
                            .title('{{ __('Web Push Notifications are not supported by your browser.') }}')
                            .body('{{ __('Use Chrome (Windows, Android, Mac) or Safari (iOS) for Web Push Notifications.') }}')
                            .danger()
                            .send();

                        return;
                    }

                    this.hasSubscription = result.subscribed;
                });
        }
    }"
>
    <x-filament::button
        [@click](https://github.com/click)="enableWebPush"
        x-show="!hasSubscription"
        x-bind:disabled="loading"
        color="primary"
    >
        <div class="flex items-center">
            <svg xmlns="http://www.w3.org/2000/svg" x-show="loading" class="size-5 mr-2 animate-spin text-white"
                 fill="#000000"
                 viewBox="0 0 256 256">
                <path
                    d="M232,128a104,104,0,0,1-208,0c0-41,23.81-78.36,60.66-95.27a8,8,0,0,1,6.68,14.54C60.15,61.59,40,93.27,40,128a88,88,0,0,0,176,0c0-34.73-20.15-66.41-51.34-80.73a8,8,0,0,1,6.68-14.54C208.19,49.64,232,87,232,128Z"></path>
            </svg>

            <span x-text="loading ? '{{ __('Enabling...') }}' : '{{ __('Enable Notifications') }}'"></span>
        </div>
    </x-filament::button>

    <x-filament::button
        [@click](https://github.com/click)="disableWebPush"
        x-show="hasSubscription"
        x-bind:disabled="loading"
        color="danger"
        outlined
    >
        <div class="flex items-center">
            <svg xmlns="http://www.w3.org/2000/svg" x-show="loading" class="size-5 mr-2 animate-spin text-danger-500"
                 fill="#000000"
                 viewBox="0 0 256 256">
                <path
                    d="M232,128a104,104,0,0,1-208,0c0-41,23.81-78.36,60.66-95.27a8,8,0,0,1,6.68,14.54C60.15,61.59,40,93.27,40,128a88,88,0,0,0,176,0c0-34.73-20.15-66.41-51.34-80.73a8,8,0,0,1,6.68-14.54C208.19,49.64,232,87,232,128Z"></path>
            </svg>

            <span x-text="loading ? '{{ __('Disabling...') }}' : '{{ __('Disable Notifications') }}'"></span>
        </div>
    </x-filament::button>
</div>

Events

webpush:ready

Fired when the WebPush functions are loaded and ready to use.

document.addEventListener("webpush:ready", () => {
    // WebPush functions are now available
});

Error Handling

All functions return a consistent response format:

{
    success: boolean,    // Whether the operation succeeded
    message: string,     // Success or error message
    error?: string       // Additional error details (only on failure)
}

Common Error Messages

• "Push notifications are not supported in this browser" - Browser doesn't support the Push API
• "Push notifications are blocked" - User has denied permission
• "Permission for notifications was denied" - User declined the permission prompt
• "No active subscription found" - Trying to unsubscribe when not subscribed
• "VAPID public key not found" - Missing configuration meta tags