ion-loading
An overlay that can be used to indicate activity while blocking user interaction. The loading indicator appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app. It includes an optional backdrop, which can be disabled by setting showBackdrop: false
upon creation.
Basic Usage
Once presented, the loading indicator will display indefinitely by default. Developers can manually dismiss the loading indicator after creation by calling the dismiss()
method on the component. The onDidDismiss
function can be called to perform an action after the loading indicator is dismissed.
Alternatively, developers can configure the loading indicator to dismiss automatically after a specific amount of time by passing the number of milliseconds to display it in the duration
of the loading options.
Controller
Inline
Ionic React and Ionic Vue users also have the option to use the ion-loading
component directly in their template.
- React
- Vue
import React, { useState } from 'react';
import { IonLoading, IonButton, IonContent } from '@ionic/react';
export const LoadingExample: React.FC = () => {
const [showLoading, setShowLoading] = useState(false);
return (
<IonContent>
<IonButton onClick={() => setShowLoading(true)}>Show Loading</IonButton>
<IonLoading
cssClass="my-custom-class"
isOpen={showLoading}
onDidDismiss={() => setShowLoading(false)}
message={'Please wait...'}
duration={5000}
/>
</IonContent>
);
};
<template>
<ion-content>
<ion-button @click="setOpen(true)">Show Loading</ion-button>
<ion-loading
:is-open="isOpenRef"
cssClass="my-custom-class"
message="Please wait..."
:duration="timeout"
@didDismiss="setOpen(false)"
>
</ion-loading>
</ion-content>
</template>
<script lang="ts">
import { IonButton, IonContent, IonLoading } from '@ionic/vue';
import { defineComponent, ref } from 'vue';
export default defineComponent({
props: {
timeout: { type: Number, default: 1000 },
},
components: { IonButton, IonContent, IonLoading },
setup() {
const isOpenRef = ref(false);
const setOpen = (state: boolean) => (isOpenRef.value = state);
return { isOpenRef, setOpen };
},
});
</script>
Customization
Spinners
The spinner that is used can be customized using the spinner
property. See the spinner property documentation for a full list of options.
Theming
Loading uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector.
We recommend passing a custom class and using that to add custom styles to the host and inner elements.
ion-loading
is presented at the root of your application, so we recommend placing any ion-loading
styles in a global stylesheet.
Interfaces
LoadingOptions
interface LoadingOptions {
spinner?: SpinnerTypes | null;
message?: string | IonicSafeString;
cssClass?: string | string[];
showBackdrop?: boolean;
duration?: number;
translucent?: boolean;
animated?: boolean;
backdropDismiss?: boolean;
mode?: Mode;
keyboardClose?: boolean;
id?: string;
htmlAttributes?: { [key: string]: any };
enterAnimation?: AnimationBuilder;
leaveAnimation?: AnimationBuilder;
}
Properties
animated
Description | If true , the loading indicator will animate. |
Attribute | animated |
Type | boolean |
Default | true |
backdropDismiss
Description | If true , the loading indicator will be dismissed when the backdrop is clicked. |
Attribute | backdrop-dismiss |
Type | boolean |
Default | false |
cssClass
Description | Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces. |
Attribute | css-class |
Type | string | string[] | undefined |
Default | undefined |
duration
Description | Number of milliseconds to wait before dismissing the loading indicator. |
Attribute | duration |
Type | number |
Default | 0 |
enterAnimation
Description | Animation to use when the loading indicator is presented. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) | undefined |
Default | undefined |
htmlAttributes
Description | Additional attributes to pass to the loader. |
Attribute | undefined |
Type | undefined | { [key: string]: any; } |
Default | undefined |
keyboardClose
Description | If true , the keyboard will be automatically dismissed when the overlay is presented. |
Attribute | keyboard-close |
Type | boolean |
Default | true |
leaveAnimation
Description | Animation to use when the loading indicator is dismissed. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) | undefined |
Default | undefined |
message
Description | Optional text content to display in the loading indicator. This property accepts custom HTML as a string. Developers who only want to pass plain text can disable the custom HTML functionality by setting innerHTMLTemplatesEnabled: false in the Ionic config. |
Attribute | message |
Type | IonicSafeString | string | undefined |
Default | undefined |
mode
Description | The mode determines which platform styles to use. |
Attribute | mode |
Type | "ios" | "md" |
Default | undefined |
showBackdrop
Description | If true , a backdrop will be displayed behind the loading indicator. |
Attribute | show-backdrop |
Type | boolean |
Default | true |
spinner
Description | The name of the spinner to display. |
Attribute | spinner |
Type | "bubbles" | "circles" | "circular" | "crescent" | "dots" | "lines" | "lines-sharp" | "lines-sharp-small" | "lines-small" | null | undefined |
Default | undefined |
translucent
Description | If true , the loading indicator will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter . |
Attribute | translucent |
Type | boolean |
Default | false |
Events
Name | Description |
---|---|
ionLoadingDidDismiss | Emitted after the loading has dismissed. |
ionLoadingDidPresent | Emitted after the loading has presented. |
ionLoadingWillDismiss | Emitted before the loading has dismissed. |
ionLoadingWillPresent | Emitted before the loading has presented. |
Methods
dismiss
Description | Dismiss the loading overlay after it has been presented. |
Signature | dismiss(data?: any, role?: string) => Promise<boolean> |
onDidDismiss
Description | Returns a promise that resolves when the loading did dismiss. |
Signature | onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
onWillDismiss
Description | Returns a promise that resolves when the loading will dismiss. |
Signature | onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
present
Description | Present the loading overlay after it has been created. |
Signature | present() => Promise<void> |
CSS Shadow Parts
No CSS shadow parts available for this component.
CSS Custom Properties
Name | Description |
---|---|
--backdrop-opacity | Opacity of the backdrop |
--background | Background of the loading dialog |
--height | Height of the loading dialog |
--max-height | Maximum height of the loading dialog |
--max-width | Maximum width of the loading dialog |
--min-height | Minimum height of the loading dialog |
--min-width | Minimum width of the loading dialog |
--spinner-color | Color of the loading spinner |
--width | Width of the loading dialog |
Slots
No slots available for this component.