0
# React Native Splash Screen
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: react-native-splash-screen
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install react-native-splash-screen`
10
- **Platform Support**: iOS, Android
11
- **React Native Compatibility**: >=0.57.0
12

13
## Core Imports
14

15
```javascript
16
import SplashScreen from 'react-native-splash-screen';
17
```
18

19
CommonJS:
20

21
```javascript
22
const SplashScreen = require('react-native-splash-screen');
23
```
24

25
## Basic Usage
26

27
```javascript
28
import React, { Component } from 'react';
29
import SplashScreen from 'react-native-splash-screen';
30

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

38
  showSplashAgain = () => {
39
    // Show splash screen programmatically
40
    SplashScreen.show();
41
    
42
    // Hide it after some time
43
    setTimeout(() => {
44
      SplashScreen.hide();
45
    }, 2000);
46
  };
47

48
  render() {
49
    return (
50
      // Your app content
51
    );
52
  }
53
}
54
```
55

56
## Capabilities
57

58
### Show Splash Screen
59

60
Displays the native splash screen programmatically.
61

62
```javascript { .api }
63
/**
64
 * Shows the splash screen
65
 * Displays native splash screen with platform-specific configuration
66
 */
67
SplashScreen.show(): void;
68
```
69

70
**Usage:**
71
```javascript
72
import SplashScreen from 'react-native-splash-screen';
73

74
// Show splash screen during async operations
75
const performAsyncOperation = async () => {
76
  SplashScreen.show();
77
  
78
  try {
79
    await someAsyncTask();
80
  } finally {
81
    SplashScreen.hide();
82
  }
83
};
84
```
85

86
### Hide Splash Screen  
87

88
Hides/dismisses the currently displayed splash screen.
89

90
```javascript { .api }
91
/**
92
 * Hides the splash screen
93
 * Dismisses the currently displayed splash screen
94
 */
95
SplashScreen.hide(): void;
96
```
97

98
### Show Custom Splash Screen (iOS)
99

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

102
```javascript { .api }
103
/**
104
 * Shows a custom splash screen from a specific storyboard or XIB file
105
 * iOS-specific method for advanced splash screen control
106
 * @param splashScreen - Name of the splash screen file (LaunchScreen, etc.)
107
 * @param rootView - Root view to display the splash screen in
108
 */
109
SplashScreen.showSplash(splashScreen: string, rootView: any): void;
110
```
111

112
**Usage:**
113
```javascript
114
import SplashScreen from 'react-native-splash-screen';
115

116
// Typical usage in componentDidMount or useEffect
117
componentDidMount() {
118
  // Perform app initialization
119
  this.initializeApp().then(() => {
120
    // Hide splash screen when ready
121
    SplashScreen.hide();
122
  });
123
}
124
```
125

126
**Usage (iOS showSplash):**
127
```javascript
128
import SplashScreen from 'react-native-splash-screen';
129
import { View } from 'react-native';
130

131
// iOS-specific custom splash screen
132
class App extends Component {
133
  componentDidMount() {
134
    // Show custom splash screen with specific storyboard
135
    SplashScreen.showSplash("LaunchScreen", this.rootView);
136
    
137
    // Later hide it
138
    setTimeout(() => {
139
      SplashScreen.hide();
140
    }, 2000);
141
  }
142
  
143
  render() {
144
    return (
145
      <View ref={ref => this.rootView = ref}>
146
        {/* App content */}
147
      </View>
148
    );
149
  }
150
}
151
```
152

153
## Types
154

155
```typescript { .api }
156
declare module "react-native-splash-screen" {
157
  export default class SplashScreen {
158
    /**
159
     * Shows the splash screen
160
     */
161
    static show(): void;
162
    
163
    /**
164
     * Hides the splash screen
165
     */
166
    static hide(): void;
167
    
168
    /**
169
     * Shows a custom splash screen (iOS only)
170
     * @param splashScreen - Name of the splash screen file
171
     * @param rootView - Root view to display the splash screen in
172
     */
173
    static showSplash(splashScreen: string, rootView: any): void;
174
  }
175
}
176
```
177

178
## Platform-Specific Behavior
179

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

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

196
## Error Handling
197

198
The library includes built-in error handling:
199

200
- **iOS**: Automatically hides splash screen if JavaScript fails to load
201
- **Android**: Includes activity state checks to prevent crashes
202
- **Both Platforms**: Methods fail silently if called in inappropriate contexts
203

204
## Installation Requirements
205

206
Beyond npm installation, platform-specific setup is required:
207

208
**Android Setup:**
209
- Add to `android/settings.gradle`
210
- Update `android/app/build.gradle` dependencies
211
- Modify `MainApplication.java` to include `SplashScreenReactPackage`
212
- Update `MainActivity.java` to call `SplashScreen.show(this)` in `onCreate`
213
- Create `launch_screen.xml` layout file in `app/src/main/res/layout`
214
- Configure theme resources and drawable assets
215
- Optionally add custom styles for fullscreen mode
216

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

224
## Testing
225

226
For Jest testing, mock the module:
227

228
```javascript
229
// __mocks__/react-native-splash-screen.js
230
export default {
231
  show: jest.fn().mockImplementation(() => { 
232
    console.log('show splash screen'); 
233
  }),
234
  hide: jest.fn().mockImplementation(() => { 
235
    console.log('hide splash screen'); 
236
  }),
237
};
238
```