Description:
@rn-nui/loading-indicator is a React Native component that provides native loading indicators with enhanced functionality.
It utilizes the modern Material 3 Expressive loading indicator on Android while defaulting to the standard ActivityIndicator on iOS.
This approach ensures your application presents a visually consistent and platform-appropriate loading state.
Features
- 🔧 Cross-platform compatibility with platform-specific optimizations and native performance.
- ⚙️ Flexible size configuration supporting both numeric values and preset options (‘small’, ‘large’).
- 🎯 Color customization for both indicator and container elements with ColorValue support.
- 📱 Android-specific container styling with configurable background circles and container colors.
- 🔄 Animation control with animating prop for show/hide functionality.
- 👁️ iOS-specific visibility management through hidesWhenStopped property.
- 🚀 Zero-configuration setup on iOS with simple installation process.
Preview
How to Use It
1. Add the package to your React Native project.
npm:
npm install @rn-nui/loading-indicatorOR Yarn:
yarn add @rn-nui/loading-indicator2. For the Material 3 Expressive indicator to render correctly on Android, you must update your app’s theme.
Open the /android/app/src/main/res/values/styles.xml file and set the parent attribute of your AppTheme style to Theme.Material3Expressive.DayNight.NoActionBar.
<resources>
<!-- Base application theme. -->
<style name="AppTheme" parent="Theme.Material3Expressive.DayNight.NoActionBar">
<!-- Your custom theme attributes can go here -->
</style>
</resources>3. No additional configuration is necessary for iOS. The component uses the built-in ActivityIndicator on this platform.
4. You can import and use the LoadingIndicator component in your application. The component is visible by default.
import React from 'react';
import { View, StyleSheet } from 'react-native';
import { LoadingIndicator } from '@rn-nui/loading-indicator';
const MyScreen = () => {
return (
<View style={styles.container}>
<LoadingIndicator />
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
});
export default MyScreen;5. The component’s appearance can be modified using several properties. The size prop accepts 'small', 'large', or a number for a custom dimension. The color prop changes the indicator’s color.
On Android, you can add a background circle with containerSize and containerColor. To control visibility, you can use the animating prop, which is useful for showing or hiding the indicator based on your application’s state.
Here is an example that shows a customized indicator that appears only when data is being fetched.
import React, { useState, useEffect } from 'react';
import { View, StyleSheet, Button } from 'react-native';
import { LoadingIndicator } from '@rn-nui/loading-indicator';
const DataFetchingComponent = () => {
const [isLoading, setIsLoading] = useState(false);
const fetchData = () => {
setIsLoading(true);
setTimeout(() => {
setIsLoading(false);
}, 3000); // Simulate a network request
};
return (
<View style={styles.container}>
{isLoading && (
<LoadingIndicator
size={60}
color="#1E90FF"
containerSize={90}
containerColor="rgba(0,0,0,0.1)"
/>
)}
<Button title="Load Data" onPress={fetchData} disabled={isLoading} />
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
gap: 20,
},
});
export default DataFetchingComponent;Related Resources
- React Native ActivityIndicator Documentation – Official React Native documentation for the underlying iOS component implementation.
- Material Design 3 Loading Indicators – Google’s official Material 3 design guidelines for loading indicator components.
- React Native Cross-Platform Development Guide – Official documentation for handling platform-specific code in React Native applications.
FAQs
Q: What is the main advantage of using this library over the default React Native ActivityIndicator?
A: The primary advantage is the automatic implementation of the modern Material 3 Expressive loading indicator on Android, which provides a more current look and feel without extra configuration beyond the theme setup. It also offers Android-specific container options for better visibility.
Q: Why is the Android theme modification required?
A: The native Material 3 components on Android rely on theme attributes for their styling. Inheriting from Theme.Material3Expressive ensures that the LoadingIndicator component has access to the necessary styles and attributes to render correctly.
Q: Can I use this library in an Expo Go project?
A: You can use this library in projects built with Expo’s development builds, but not in the Expo Go app. The requirement to modify native Android files (styles.xml) means you need a custom development client or a standalone build.
Q: Are the containerSize and containerColor props available for iOS?
A: No, these two props are specific to the Android implementation and will have no effect on iOS.
