SplashScreenManager

SplashScreenManager allows you to override control of the app's native splash screen lifecycle, so you can force it to remain visible until it is explicitly hidden.

Splash screens can be either static or animated. Both cases are achieved with .png images.

Assets

Splash screen assets are picked up by the native animation service on app launch. In order to configure them to be picked up, splash screen frame(s) need to be compressed into a .zip file along with a descriptor file.

Images

Mandatory Naming Conventions

All splash screen images must follow this exact naming format:

• Format: loopXXXXX.png
  • Where XXXXX is a 5-digit number starting from 00000
  • Numbers must be zero-padded

Example sequence: loop00000.png, loop00001.png, loop00002.png, etc.

Common Mistakes to Avoid

• image0.png (incorrect naming)
• loop1.png (missing zero padding)
• loop_00001.png (incorrect underscore)
• LOOP00001.png (incorrect capitalization)

If your application targets multiple devices, please ensure that the resolution of your splash screen images are appropriate for the target that demands the highest resolution.

• Use .png image(s)
  • Single .png image for a static splash screen
  • Multiple .png images for an animated splash screen
  • Imag naming must follow the specified naming convention
• Put your image(s) in a folder named _loop
  • Even if you only have one image, it needs to be put into _loop
• Supported image resolutions
  • Multimodal profile: 960x480
  • TV profile: 1920x1080

Note: 4K resolution assets are not supported.

Example

_loop
├── loop00000.png
├── loop00001.png
├── loop00002.png
├── loop00003.png
├── loop00004.png
└── loop00005.png

Descriptor File

A descriptor file is needed to give the animation service some information about the native splash screen. Data such as image dimensions, fps, and settings for the splash screen can be specified here. This descriptor file will be compressed with _loop into a .zip for the animation service to pick up. To create a descriptor file, create a new .txt file and follow the instructions below:

• Name your descriptor file desc.txt
• First line should be image width, image height and desired fps separated by spaces
• Second line should be c 0 0 _loop
  • c: keep assets after done looping
  • 0: loop infinitely until terminated
  • 0: fps delay until next command (not relevant for splash screen)
  • _loop: name of folder

Example

The following example sets the width to 480, the height to 128, and the fps to 30.

420 128 30 
c 0 0 _loop

SplashScreenImages.zip

• From your Terminal, navigate to the directory where _loop and desc.txt are located
• Run zip SplashScreenImages.zip _loop/* desc.txt to create SplashScreenImages.zip

NOTE: on Mac, right-click and "Compress" can lead to an extra outer folder being created which will cause issues when the native service tries to locate the assets. Please use zip from the command line on the two individual items to avoid this issue.

Example

SplashScreenImages.zip
├── _loop
│   ├── loop00000.png
│   ├── loop00001.png
│   ├── loop00002.png
│   ├── loop00003.png
│   ├── loop00004.png
│   └── loop00005.png
└── desc.txt

Placement in Package

• If it does not exist, create directory: <package root>/assets/raw
• Place SplashScreenImages.zip inside

Example

application/
├── CMakeLists.txt
├── CONTRIBUTING.md
├── Config
├── README.md
├── assets
│   └── raw
│       └── SplashScreenImages.zip
├── build
├── build-tools
├── buildinfo.json
├── bundle
├── cmake
├── docs
├── manifest.toml
└── src

Usage

The following example shows the typical usage of the splash screen manager. The code uses KitchenSinkApp as a place holder component name. When implementing your splash screen, replace this with the appropriate component name.

import React, { useEffect, useState } from 'react';
import { Text, View } from 'react-native';
import { useHideSplashScreenCallback, usePreventHideSplashScreen } from '@amzn/react-native-kepler';

export default function App() {
  usePreventHideSplashScreen();

  const [isAppReady, setIsAppReady] = useState(false);

  // Begin loading application content (network requests, etc.)
  // Using 2 second timeout as dummy for loading content
  setTimeout(() => setIsAppReady(true), 2000);
  const hideSplashScreenCallback = useHideSplashScreenCallback();

  useEffect(() => {
    if (isAppReady) {
      // Hide the splash screen and render content
      hideSplashScreenCallback();
    }
}, [isAppReady]);
  
  return (
    <View
      style={{
        flex: 1,
        alignItems: 'center',
        justifyContent: 'center'
      }}
    >
      <Text> SplashScreen Demo! </Text>
    </View>
  );
}

Reference

Methods

preventAutoHideAsync()

Replaced by the usePreventHideSplashScreen() hook.

preventAutoHideAsync(moduleName);

Override the automatic splash screen lifecycle which dismisses the splash screen when the first contentful frame is ready to render (at the end of the first set of mounting instructions). Invoking this API will prevent the splash screen for the module from being dismissed until hideAsync(moduleName) is explicitly invoked.

For KeplerSDK app developers, the moduleName parameter maps to the name field in your app’s app.json file.

Users of this API are recommended to call it in global scope. Calling this in a React component or hook could lead to bugs if it causes this API to be called after the splash screen is already dismissed.

hideAsync()

Replaced by the useHideSplashScreenCallback() hook.

hideAsync(moduleName);

Hide the splash screen immediately. To avoid any flicker, be sure that your app content is ready to be displayed before invoking this method.

For KeplerSDK app developers, the moduleName parameter maps to the name field in your app’s app.json file.

usePreventHideSplashScreen()

usePreventHideSplashScreen(): void

Overrides the automatic splash screen lifecycle which dismisses the splash screen when the first full content frame is ready to render (at the end of the first set of mounting instructions). Invoking this custom hook prevents the splash screen for the module from being dismissed.

Note: Call this hook called in the root component of your application. Make sure to also obey the Rules of Hooks, when calling this hook.

useHideSplashScreenCallback()

useHideSplashScreenCallback(): () => void

Invoking this custom hook returns a callback function that, when invoked, hides the splash screen. Invoking the hook itself does not dismiss the splash screen.

Call this hook in the root component of your application. Make sure to also obey the Rules of Hooks when calling this hook.

While it is safe to invoke the callback multiple times, subsequent calls will lead to the app trying to dismiss a splash screen that is already dismissed. This will show up as error logs. To avoid this, ensure the callback returned from the hook is executed only once for your app. You can do this by adding the callback invocation inside of a useEffect hook.

Last updated: Sep 30, 2025