# @capacitor/splash-screen
The Splash Screen API provides methods for showing or hiding a Splash image.
## Install
```bash
npm install @capacitor/splash-screen
npx cap sync
```
## Example
```typescript
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](https://capacitorjs.com/docs/config).
## 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](https://capacitorjs.com/docs/config).
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](https://developer.android.com/reference/android/widget/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`:
```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`:
```ts
///
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:
```xml
```
## Example Guides
[Adding Your Own Icons and Splash Screen Images ›](https://www.joshmorony.com/adding-icons-splash-screens-launch-images-to-capacitor-projects/)
[Creating a Dynamic/Adaptable Splash Screen for Capacitor (Android) ›](https://www.joshmorony.com/creating-a-dynamic-universal-splash-screen-for-capacitor-android/)
## API
* [`show(...)`](#show)
* [`hide(...)`](#hide)
* [Interfaces](#interfaces)
### show(...)
```typescript
show(options?: ShowOptions | undefined) => Promise
```
Show the splash screen
| Param | Type |
| ------------- | --------------------------------------------------- |
| **`options`** | ShowOptions |
**Since:** 1.0.0
--------------------
### hide(...)
```typescript
hide(options?: HideOptions | undefined) => Promise
```
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 |