Nearest Phase Modulator

    @capacitor/splash-screen
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.2 • Public • Published

    @capacitor/splash-screen

    The Splash Screen API provides methods for showing or hiding a Splash image.

    Install

    npm install @capacitor/splash-screen
    npx cap sync

    Example

    import { SplashScreen } from '@capacitor/splash-screen';
    
    // Hide the splash (you should do this on app launch)
    await SplashScreen.hide();
    
    // Show the splash for an indefinite amount of time:
    await SplashScreen.show({
      autoHide: false
    });
    
    // Show the splash for two seconds and then automatically hide it:
    await SplashScreen.show({
      showDuration: 2000,
      autoHide: true
    });

    Hiding the Splash Screen

    By default, the Splash Screen is set to automatically hide after 500 ms.

    If you want to be sure the splash screen never disappears before your app is ready, set launchAutoHide to false; the splash screen will then stay visible until manually hidden. For the best user experience, your app should call hide() as soon as possible.

    If, instead, you want to show the splash screen for a fixed amount of time, set launchShowDuration in your Capacitor configuration file.

    Background Color

    In certain conditions, especially if the splash screen does not fully cover the device screen, it might happen that the app screen is visible around the corners (due to transparency). Instead of showing a transparent color, you can set a backgroundColor to cover those areas.

    Possible values for backgroundColor are either #RRGGBB or #RRGGBBAA.

    Spinner

    If you want to show a spinner on top of the splash screen, set showSpinner to true in your Capacitor configuration file.

    You can customize the appearance of the spinner with the following configuration.

    For Android, androidSpinnerStyle has the following options:

    • horizontal
    • small
    • large (default)
    • inverse
    • smallInverse
    • largeInverse

    For iOS, iosSpinnerStyle has the following options:

    • large (default)
    • small

    To set the color of the spinner use spinnerColor, values are either #RRGGBB or #RRGGBBAA.

    Configuration

    These config values are available:

    Prop Type Description Default Since
    launchShowDuration number How long to show the launch splash screen when autoHide is enabled (in ms) 500 1.0.0
    launchAutoHide boolean Whether to auto hide the splash after launchShowDuration. true 1.0.0
    backgroundColor string Color of the background of the Splash Screen in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if useDialog is true. 1.0.0
    androidSplashResourceName string Name of the resource to be used as Splash Screen. Only available on Android. splash 1.0.0
    androidScaleType 'CENTER' | 'CENTER_CROP' | 'CENTER_INSIDE' | 'FIT_CENTER' | 'FIT_END' | 'FIT_START' | 'FIT_XY' | 'MATRIX' The ImageView.ScaleType used to scale the Splash Screen image. Doesn't work if useDialog is true. Only available on Android. FIT_XY 1.0.0
    showSpinner boolean Show a loading spinner on the Splash Screen. Doesn't work if useDialog is true. 1.0.0
    androidSpinnerStyle 'horizontal' | 'small' | 'large' | 'inverse' | 'smallInverse' | 'largeInverse' Style of the Android spinner. Doesn't work if useDialog is true. large 1.0.0
    iosSpinnerStyle 'small' | 'large' Style of the iOS spinner. Doesn't work if useDialog is true. Only available on iOS. large 1.0.0
    spinnerColor string Color of the spinner in hex format, #RRGGBB or #RRGGBBAA. Doesn't work if useDialog is true. 1.0.0
    splashFullScreen boolean Hide the status bar on the Splash Screen. Only available on Android. 1.0.0
    splashImmersive boolean Hide the status bar and the software navigation buttons on the Splash Screen. Only available on Android. 1.0.0
    layoutName string If useDialog is set to true, configure the Dialog layout. If useDialog is not set or false, use a layout instead of the ImageView. Only available on Android. 1.1.0
    useDialog boolean Use a Dialog instead of an ImageView. If layoutName is not configured, it will use a layout that uses the splash image as background. Only available on Android. 1.1.0

    Examples

    In capacitor.config.json:

    {
      "plugins": {
        "SplashScreen": {
          "launchShowDuration": 3000,
          "launchAutoHide": true,
          "backgroundColor": "#ffffffff",
          "androidSplashResourceName": "splash",
          "androidScaleType": "CENTER_CROP",
          "showSpinner": true,
          "androidSpinnerStyle": "large",
          "iosSpinnerStyle": "small",
          "spinnerColor": "#999999",
          "splashFullScreen": true,
          "splashImmersive": true,
          "layoutName": "launch_screen",
          "useDialog": true
        }
      }
    }

    In capacitor.config.ts:

    /// <reference types="@capacitor/splash-screen" />
    
    import { CapacitorConfig } from '@capacitor/cli';
    
    const config: CapacitorConfig = {
      plugins: {
        SplashScreen: {
          launchShowDuration: 3000,
          launchAutoHide: true,
          backgroundColor: "#ffffffff",
          androidSplashResourceName: "splash",
          androidScaleType: "CENTER_CROP",
          showSpinner: true,
          androidSpinnerStyle: "large",
          iosSpinnerStyle: "small",
          spinnerColor: "#999999",
          splashFullScreen: true,
          splashImmersive: true,
          layoutName: "launch_screen",
          useDialog: true,
        },
      },
    };
    
    export default config;

    Android

    To use splash screen images named something other than splash.png, set androidSplashResourceName to the new resource name. Additionally, in android/app/src/main/res/values/styles.xml, change the resource name in the following block:

    <style name="AppTheme.NoActionBarLaunch" parent="AppTheme.NoActionBar">
        <item name="android:background">@drawable/NAME</item>
    </style>

    Example Guides

    Adding Your Own Icons and Splash Screen Images ›

    Creating a Dynamic/Adaptable Splash Screen for Capacitor (Android) ›

    API

    show(...)

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

    Show the splash screen

    Param Type
    options ShowOptions

    Since: 1.0.0


    hide(...)

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

    Hide the splash screen

    Param Type
    options HideOptions

    Since: 1.0.0


    Interfaces

    ShowOptions

    Prop Type Description Default Since
    autoHide boolean Whether to auto hide the splash after showDuration 1.0.0
    fadeInDuration number How long (in ms) to fade in. 200 1.0.0
    fadeOutDuration number How long (in ms) to fade out. 200 1.0.0
    showDuration number How long to show the splash screen when autoHide is enabled (in ms) 3000 1.0.0

    HideOptions

    Prop Type Description Default Since
    fadeOutDuration number How long (in ms) to fade out. 200 1.0.0

    Install

    npm i @capacitor/splash-screen

    DownloadsWeekly Downloads

    55,188

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    95.6 kB

    Total Files

    35

    Last publish

    Collaborators

    • itschaced
    • it_mike_s
    • larsmikkelsen
    • giralte-ionic
    • steven0351-ionic
    • jpender
    • ionicjs
    • maxlynch
    • mhartington
    • jcesarmobile
    • cmapoole
    • nhyatt