or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-react-native-splash-screen

A splash screen API for React Native that provides programmatic control over splash screen visibility on iOS and Android platforms.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-native-splash-screen@3.3.x

To install, run

npx @tessl/cli install tessl/npm-react-native-splash-screen@3.3.0

index.mddocs/

React Native Splash Screen

React Native Splash Screen provides programmatic control over native splash screens on iOS and Android platforms. It allows developers to show and hide splash screens dynamically during app initialization and loading processes.

Package Information

  • Package Name: react-native-splash-screen
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install react-native-splash-screen
  • Platform Support: iOS, Android
  • React Native Compatibility: >=0.57.0

Core Imports

import SplashScreen from 'react-native-splash-screen';

CommonJS:

const SplashScreen = require('react-native-splash-screen');

Basic Usage

import React, { Component } from 'react';
import SplashScreen from 'react-native-splash-screen';

export default class App extends Component {
  componentDidMount() {
    // Hide splash screen when app has loaded
    // This is the most common usage pattern
    SplashScreen.hide();
  }

  showSplashAgain = () => {
    // Show splash screen programmatically
    SplashScreen.show();
    
    // Hide it after some time
    setTimeout(() => {
      SplashScreen.hide();
    }, 2000);
  };

  render() {
    return (
      // Your app content
    );
  }
}

Capabilities

Show Splash Screen

Displays the native splash screen programmatically.

/**
 * Shows the splash screen
 * Displays native splash screen with platform-specific configuration
 */
SplashScreen.show(): void;

Usage:

import SplashScreen from 'react-native-splash-screen';

// Show splash screen during async operations
const performAsyncOperation = async () => {
  SplashScreen.show();
  
  try {
    await someAsyncTask();
  } finally {
    SplashScreen.hide();
  }
};

Hide Splash Screen

Hides/dismisses the currently displayed splash screen.

/**
 * Hides the splash screen
 * Dismisses the currently displayed splash screen
 */
SplashScreen.hide(): void;

Show Custom Splash Screen (iOS)

Shows a custom splash screen with specific configuration for iOS platform.

/**
 * Shows a custom splash screen from a specific storyboard or XIB file
 * iOS-specific method for advanced splash screen control
 * @param splashScreen - Name of the splash screen file (LaunchScreen, etc.)
 * @param rootView - Root view to display the splash screen in
 */
SplashScreen.showSplash(splashScreen: string, rootView: any): void;

Usage:

import SplashScreen from 'react-native-splash-screen';

// Typical usage in componentDidMount or useEffect
componentDidMount() {
  // Perform app initialization
  this.initializeApp().then(() => {
    // Hide splash screen when ready
    SplashScreen.hide();
  });
}

Usage (iOS showSplash):

import SplashScreen from 'react-native-splash-screen';
import { View } from 'react-native';

// iOS-specific custom splash screen
class App extends Component {
  componentDidMount() {
    // Show custom splash screen with specific storyboard
    SplashScreen.showSplash("LaunchScreen", this.rootView);
    
    // Later hide it
    setTimeout(() => {
      SplashScreen.hide();
    }, 2000);
  }
  
  render() {
    return (
      <View ref={ref => this.rootView = ref}>
        {/* App content */}
      </View>
    );
  }
}

Types

declare module "react-native-splash-screen" {
  export default class SplashScreen {
    /**
     * Shows the splash screen
     */
    static show(): void;
    
    /**
     * Hides the splash screen
     */
    static hide(): void;
    
    /**
     * Shows a custom splash screen (iOS only)
     * @param splashScreen - Name of the splash screen file
     * @param rootView - Root view to display the splash screen in
     */
    static showSplash(splashScreen: string, rootView: any): void;
  }
}

Platform-Specific Behavior

Android

  • Uses native Dialog with custom theme (R.style.SplashScreen_SplashTheme)
  • Supports fullscreen mode (R.style.SplashScreen_Fullscreen)
  • Automatically handles activity lifecycle and state management
  • Configurable through theme resources and layout files (launch_screen.xml)
  • Native methods support optional theme resource ID and fullscreen parameters
  • Built-in Android P (API 28+) display cutout support for fullscreen mode

iOS

  • Uses UIView overlay approach with LaunchScreen integration
  • Integrates with Launch Screen storyboards and XIB files
  • Automatically handles JavaScript load error scenarios (auto-hide on JS errors)
  • Supports custom splash screen views via showSplash method
  • Uses main thread dispatch queues for UI operations
  • Built-in waiting mechanism during JavaScript bundle loading

Error Handling

The library includes built-in error handling:

  • iOS: Automatically hides splash screen if JavaScript fails to load
  • Android: Includes activity state checks to prevent crashes
  • Both Platforms: Methods fail silently if called in inappropriate contexts

Installation Requirements

Beyond npm installation, platform-specific setup is required:

Android Setup:

  • Add to android/settings.gradle
  • Update android/app/build.gradle dependencies
  • Modify MainApplication.java to include SplashScreenReactPackage
  • Update MainActivity.java to call SplashScreen.show(this) in onCreate
  • Create launch_screen.xml layout file in app/src/main/res/layout
  • Configure theme resources and drawable assets
  • Optionally add custom styles for fullscreen mode

iOS Setup:

  • Add to iOS project via CocoaPods (pod install) or manual Xcode integration
  • Update AppDelegate.m to import RNSplashScreen.h and call [RNSplashScreen show]
  • Configure Launch Screen storyboard or XIB files in Xcode
  • For custom splash screens, use showSplash:inRootView: method
  • Ensure proper header search paths are configured

Testing

For Jest testing, mock the module:

// __mocks__/react-native-splash-screen.js
export default {
  show: jest.fn().mockImplementation(() => { 
    console.log('show splash screen'); 
  }),
  hide: jest.fn().mockImplementation(() => { 
    console.log('hide splash screen'); 
  }),
};