capacitor-splash-screen

👉 NOTE: This plugin does not yet work with Capacitor 3.

This Capacitor 2 plugin provides complete control over native splash screens, both automatically at launch and via code.

Features
Installation
Configuration
Usage
Custom animation
API

Features

• On iOS, both images and storyboards are supported.
• On Android, both images and layouts are supported.
• Seamless, automatic transition from an iOS app’s launch screen to an identical splash screen.
• Support for all native image sizing and placement modes.
• Complete control over timing: delay, fade in, duration, fade out.
• Specify time units in seconds or milliseconds.
• Control over the splash screen background, including alpha.
• Support for dark mode (iOS only).
• Hooks for user animation of a splash screen.

A demo which shows all of the features can be found here.

Installation

pnpm install @aparajita/capacitor-splash-screen  # npm install, yarn add

Configuration

Every property in the WSSplashScreenShowOptions and WSSplashScreenHideOptions interfaces can be specified in the plugin’s config file or passed as options to the plugin method — except for delay, which can only be passed in the method options.

👉NOTE You must specify launch screen WSSplashScreenShowOptions in the config file.

Any property that is not passed in method options falls back to the value in the config file, and if the property is not in the config file, the documented default is used. This allows you to specify common behavior in the config file, and pass only the properties that need to be overridden in options.

Platform-specific config

There are several config properties that are specific to iOS or Android, e.g. iosImageDisplayMode and androidImageDisplayMode. Platform-specific properties may be specified in two ways:

• At the top level, with the platform prefix.
• In a platform subobject, without the prefix.

For example, iosImageDisplayMode and androidImageDisplayMode may be specified in either of these ways, both in the plugin config file and in options passed to the show() method:

Method options

const options: WSSplashScreenShowOptions = {
  iosImageDisplayMode: 'fit',
  androidImageDisplayMode: 'center'
}

const options: WSSplashScreenShowOptions = {
  ios: {
      imageDisplayMode: 'fit'
  },
  android: {
      imageDisplayMode: 'center'
  }
}

JSON config file

{
  "iosImageDisplayMode": "fit",
  "androidImageDisplayMode": "center"
}

{
  "ios": {
    "imageDisplayMode": "fit"
  },
  "android": {
    "imageDisplayMode": "center"
  }
}

By group platform-specific options in a subobject, it’s much easier to find them.

Breaking changes from the legacy plugin

autoHide In the legacy plugin, autoHide is true by default. In this plugin, it is false by default, which means you must manually call hide() yourself when your app is loaded. Why? Because guessing how long your app will take to load is bound to be wrong most of the time. So the tendency will be to make it much longer than necessary, which degrades the user experience.

launch config In the legacy plugin, there was separate config for the launch splash screen and for a splash screen shown programmatically. Because all possible options can be passed to the show() and hide() methods, this dichotomy is no longer necessary, and there is only one unified set of configuration options.

Usage

There are two scenarios for splash screens: launch and programmatic.

Launch screens

For a launch splash screen, do the following:

• Set the source to the name of your launch image or storyboard (iOS) / layout (Android).
• Configure the rest of the show options. Either do not set autoHide, or set it to false.
• In your app’s code, when it is fully mounted, call hide({ delay: <some number> }) (standard fade out) or animate({ delay: <some_number> }) (your custom animation), where <some number> will usually be around 150 (milliseconds) or more.

The delay is necessary because:

1. Capacitor creates the web view.
2. The web view loads your app.
3. Your app is mounted in the DOM, but has not yet been rendered.
4. You call hide() or animate().
5. The web view renders the content generated by your app.

When you call hide() or animate(), the web view has not yet been rendered. If you hide too quickly, there will be a flash of the web view’s background color just before it renders. That’s why a small delay is necessary.

Programmatic splash screens

Programmatically created splash screens are identical to launch splash screens, with the exception that you must call show() yourself and you are not limited to the show options in the plugin config file. You may pass any or all show options in the method call.

Showing a splash screen on app resume

If you have a fancy branded splash screen, you may wish to show it every time the app becomes active. This plugin provides a convenience function to make that easy to do.

👉NOTE: Currently this only seems to work on iOS.

// This is Capacitor 2 code
import { listenToAppState, WSSplashScreen } from '@capacitor/splash-screen';

if (Capacitor.getPlatform() === 'ios') {
  listenToAppState(true, {
    async onSuspend() {
      await WSSplashScreen.show({
        fadeInDuration: 0.2,
        backgroundColor: 'systemBackground'
      })
    },

    async onResume() {
      await WSSplashScreen.animate({ delay: 0.2 })
    }
  })
}

The trick we are playing here is to show the splash screen as the app is suspended, so that when the app is resumed, the splash screen is already visible, and then we just need to animate it. 😎

Custom animation

Splash Screen supports custom animation on both iOS and Android. The demo app contains custom animation on both platforms, which you can use as a template for your animation.

In general, to animate a splash screen, you need to do the following:

• Make sure that the animated option is true, either in the plugin config or in the options passed to the show() plugin method.
• Call the show() plugin method (unless it’s at launch, when that is done for you), and when that returns;
• Call the animate() plugin method. You may pass arbitrary values to your animation code through the animate() options.

Events

There are three animation events sent to your animation method. Of the three, you are only required to respond to the animate event.

• beforeShow — This event is sent after the splash screen and spinner views have been built, but just before they are faded in. If you need to create or modify views, this is the place to do it.
• animate — This event is sent when the animate() method is called, after any delay specified in the method options.
• afterShow — This event is sent after the animation is finished and the splash screen and spinner have been removed from their superview. If you created your own views, this is the place to remove them.

Event handler

In order to receive animation events (and thus perform animation), you need to create an animation handler method in your app’s native code. On iOS, the event handler will look like this:

enum EventType: String {
  case animate
  case beforeShow
  case afterShow
}

@objc func onSplashScreenEvent(_ event: String, _ params: Any) {
  guard let params = params as? [String: Any],
        let eventType = EventType(rawValue: event) else {
    return
  }

  switch eventType {
  case .animate:
    animate(withParams: params)

  case .beforeShow:
    handleBeforeShow(params: params)

  case .afterShow:
    handleAfterShow(params: params)
  }
}

On Android, the event handler will look like this:

public void onSplashScreenEvent(String event, HashMap<String, Object> params) {
    switch (event) {
        case "beforeShow":
            onBeforeShow(params);
            break;

        case "afterShow":
            onAfterShow(params);
            break;

        case "animate":
            animate(params);
            break;
    }
}

👉IMPORTANT❗️ The method names and signatures must be exactly as displayed above.

Event parameters

Each event receives parameters from the plugin with context that you may need in performing your animation. All of the events receive the first four of the following parameters. The done parameter is only passod to the animate event.

As noted above, you must call the done callback when the animation is completely done, otherwise control will not be returned to the JavaScript runtime. In most cases you will do this in the animation completion function.

API

show(options?: WSSplashScreenShowOptions | undefined) => Promise<void>

hide(options?: WSSplashScreenHideOptions | undefined) => Promise<void>

animate(options?: WSSplashScreenAnimateOptions | undefined) => Promise<void>