React Native Progress Indicators

Common errors

• Invariant Violation: requireNativeComponent: 'RNSVGPath' was not found in the UIManager.

  cause The `react-native-svg` library is either not installed or not correctly linked for React Native projects, specifically after the v5.0.0 migration.
  fix Install `react-native-svg` (`npm install react-native-svg`) and ensure it's properly linked according to its documentation, especially for React Native versions prior to 0.60 where autolinking might not cover all cases. Clean your build cache if needed.

• Warning: Animated: `useNativeDriver` was not specified. This is a new required parameter for `Animated` functions...

  cause This warning occurs when the `useNativeDriver` prop is omitted from `Progress.Bar` components, particularly in older versions.
  fix Explicitly set `useNativeDriver={false}` (or `true` if appropriate and supported for your animation config) on your `Progress.Bar` component. Update to `react-native-progress` v4.1.1 or higher to mitigate this for default scenarios.

• TypeError: Cannot read property 'ARTText' of undefined

  cause This usually indicates an issue with `react-native-art` (or the `react-native-community/art` fork) not being correctly linked or installed, which is used by `ProgressBar`.
  fix Ensure that `react-native-art` or the `@react-native-community/art` package is correctly installed and linked in your project. Check React Native version compatibility with the `react-native-progress` version and its ART dependency.

Warnings

• breaking Version 5.0.0 introduced a breaking change by migrating to `react-native-svg`. Projects using `Progress.Pie` or `Progress.Circle` must now explicitly install `react-native-svg` as a peer dependency.
  Fix: Ensure `react-native-svg` is installed in your project: `npm install react-native-svg` or `yarn add react-native-svg`. Follow its installation instructions for linking if necessary for older RN versions.
• breaking Version 4.0.0 migrated to the RNC ART library to support React Native 0.60+. This also involved migrating from deprecated lifecycle methods, potentially requiring updates to custom component wrappers.
  Fix: Upgrade to React Native 0.60+ or ensure your ART setup is compatible. Review any custom component logic for deprecated lifecycle methods.
• gotcha The `Progress.Pie` and `Progress.Circle` components require the `react-native-svg` peer dependency. If not installed, these components will fail to render.
  Fix: Install `react-native-svg` (`npm install react-native-svg`) or use deep imports like `import ProgressBar from 'react-native-progress/Bar';` if only the bar component is needed.
• gotcha When using `Progress.Bar` with animations, `useNativeDriver` should be explicitly declared to avoid warnings. This was fixed in v4.1.1/v4.1.2.
  Fix: Set the `useNativeDriver` prop explicitly to `true` or `false` (default is `false`) on `Progress.Bar` to suppress the warning, e.g., `<Progress.Bar useNativeDriver={false} ... />`.

Install

• npm install react-native-progress npm
• yarn add react-native-progress yarn
• pnpm add react-native-progress pnpm

Imports

• * as Progress
  wrong:

  const Progress = require('react-native-progress');

  correct:

  import * as Progress from 'react-native-progress';

  This is the primary import for accessing all components (Bar, Pie, Circle, CircleSnail). Prefer named imports for better tree-shaking where possible, or deep imports for specific components.
• ProgressBar

  import ProgressBar from 'react-native-progress/Bar';

  Use this deep import if you only need the ProgressBar and want to avoid installing 'react-native-svg' and its dependencies. This component uses the `react-native-art` library instead.
• CircleSnail
  wrong:

  import CircleSnail from 'react-native-progress/CircleSnail';

  correct:

  import { CircleSnail } from 'react-native-progress';

  While a deep import for CircleSnail might seem intuitive, it's typically exported as a named member from the main entry point.
• ProgressBarProps

  import type { ProgressBarProps } from 'react-native-progress';

  For TypeScript users, import component props types directly from the package root for stronger type checking.

Quickstart

This example demonstrates how to import and use the various progress components (Bar, Pie, Circle, CircleSnail), showcasing both determinate and indeterminate states with custom styling.

import React from 'react';
import { View, StyleSheet, Text } from 'react-native';
import * as Progress from 'react-native-progress';

const App = () => {
  const progressValue = 0.6;
  const indeterminateValue = true;

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Progress Bar</Text>
      <Progress.Bar progress={progressValue} width={200} color="#4CAF50" unfilledColor="#E0E0E0" />

      <Text style={styles.title}>Progress Pie</Text>
      <Progress.Pie progress={progressValue} size={80} color="#FFC107" unfilledColor="#E0E0E0" borderWidth={2} />

      <Text style={styles.title}>Progress Circle (Indeterminate)</Text>
      <Progress.Circle size={60} indeterminate={indeterminateValue} color="#2196F3" borderWidth={3} />

      <Text style={styles.title}>Circle Snail</Text>
      <Progress.CircleSnail 
        color={['#F44336', '#9C27B0', '#00BCD4']} 
        duration={1500}
        direction="counter-clockwise"
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
    paddingTop: 50,
    gap: 20
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginTop: 10
  }
});

export default App;