ios-pwa-splash-screen

Add iOS and iPadOS PWA splash screens generated from your app icons.

Demo

Features

• Creates portrait and landscape <link rel="apple-touch-startup-image"> tags
• Supports separate light and dark mode icons
• Detects iOS and iPadOS by default
• Replaces previously generated tags when run again
• Includes ESM, CommonJS, UMD, and TypeScript declarations

Install

npm install ios-pwa-splash-screen

Basic usage

Define a setup function:

// src/pwa-splash.ts
import { generateIosPwaSplash } from 'ios-pwa-splash-screen';

export function setupIosSplashScreen() {
  generateIosPwaSplash({
    icon: { url: '/icons/icon-light.png', backgroundColor: '#fff' },
    iconDark: { url: '/icons/icon-dark.png', backgroundColor: '#000' },
  }).catch(console.error);
}

Run it from a browser entry point:

import { setupIosSplashScreen } from './pwa-splash';

setupIosSplashScreen();

Local icon URLs need no extra configuration. For an icon hosted on another origin, that server must allow CORS and crossOrigin: 'anonymous' must be set. Set ensureIos: false when testing on a non-iOS device.

Framework examples

These examples use setupIosSplashScreen from above.

React and Next.js

'use client'; // Required by the Next.js App Router.

import { useEffect } from 'react';
import { setupIosSplashScreen } from './pwa-splash';

export function PwaSplashSetup() {
  useEffect(() => setupIosSplashScreen(), []);

  return null;
}

Render <PwaSplashSetup /> in the root component or layout.

Vue and Nuxt

Call it from the root App.vue or layout:

<script setup lang="ts">
import { onMounted } from 'vue';
import { setupIosSplashScreen } from './pwa-splash';

onMounted(setupIosSplashScreen);
</script>

Svelte and SvelteKit

Call it from the root component or +layout.svelte:

<script lang="ts">
  import { onMount } from 'svelte';
  import { setupIosSplashScreen } from './pwa-splash';

  onMount(setupIosSplashScreen);
</script>

Angular

import { afterNextRender, Component } from '@angular/core';
import { setupIosSplashScreen } from './pwa-splash';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  constructor() {
    afterNextRender(setupIosSplashScreen);
  }
}

Astro

Call it from a <script> in the root layout:

<script>
  import { setupIosSplashScreen } from './pwa-splash';

  setupIosSplashScreen();
</script>

CDN usage

The examples use unpkg. For jsDelivr, replace https://unpkg.com/ with https://cdn.jsdelivr.net/npm/.

ES module

<script type="module">
  import { generateIosPwaSplash } from 'https://unpkg.com/ios-pwa-splash-screen/dist/index.js';

  generateIosPwaSplash({
    icon: { url: '/icon-light.png', backgroundColor: '#fff' },
    iconDark: { url: '/icon-dark.png', backgroundColor: '#000' },
  }).catch(console.error);
</script>

UMD

<script src="https://unpkg.com/ios-pwa-splash-screen/dist/index.umd.js"></script>

<script>
  window.IosPwaSplashScreen.generateIosPwaSplash({
    icon: { url: '/icon-light.png', backgroundColor: '#fff' },
    iconDark: { url: '/icon-dark.png', backgroundColor: '#000' },
  }).catch(console.error);
</script>

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | icon | IconConfig | required | Light-mode icon configuration | | iconDark | IconConfig | None | Dark-mode icon configuration | | ensureIos | boolean | true | Only run on iOS and iPadOS | | ensureMetaTags | boolean | true | Ensure the Apple web-app-capable meta tag exists | | crossOrigin | 'anonymous' \| 'use-credentials' | None | Set img.crossOrigin when loading icons | | imageType | 'image/png' \| 'image/jpeg' | 'image/png' | Generated image format | | quality | number | 1 | JPEG quality from 0 to 1 | | fetchPriority | 'low' \| 'high' \| 'auto' | 'high' | Icon image fetch priority | | cleanup | boolean | true | Remove previously generated startup-image tags | | customAttribute | string | 'data-pwa-splash-generated' | Attribute used to identify generated tags |

IconConfig

| Property | Type | Default | Description | | --- | --- | --- | --- | | url | string | required | Square icon URL | | backgroundColor | string | required | Splash screen background color | | margin | number | 25 | Icon margin as a percentage of the shorter screen edge |

License

MIT © VastBlast