react-native-circular-progress

1.4.1 verified Sat Apr 25 auth: no javascript

A React Native component for creating animated, circular progress indicators using SVG. Version 1.4.1 is the latest stable release, with infrequent updates. It leverages react-native-svg for rendering, supports animated transitions, and offers customizable size, width, tint color, background color, line caps, arc sweep angle, and children functions for displaying progress text. Differentiators include a simple API, TypeScript types, and the ability to render caps and manually trigger timing animations via the animate() method. Peer dependencies: react >=16.0.0, react-native >=0.50.0, react-native-svg >=7.0.0.

Common errors

error Error: 'react-native-svg' is not installed. Please install react-native-svg in your project. ↓

cause Missing peer dependency react-native-svg.

fix

npm install react-native-svg

error Invariant Violation: `AnimatedCircularProgress` has been rendered with both `fill` and `children` as a function. Only one of these should be used. ↓

cause Passing both a fill value and a function as children, or incorrectly using children.

fix

Either use fill prop to set progress and children as a render function to display current progress, or use children as static content without fill.

error TypeError: Cannot read property 'width' of undefined ↓

cause Missing required 'size' or 'width' prop on CircularProgress.

fix

Ensure both size and width are provided as numbers. Example: <AnimatedCircularProgress size={120} width={15} />

Warnings

gotcha The 'fill' prop is a percentage (0-100), not a fraction. ↓

fix Use values between 0 and 100 for fill, e.g., fill={75} for 75%.

deprecated The 'prePolar' prop is deprecated and removed in v1.4.0. Use 'rotation' instead. ↓

fix Replace prePolar with rotation (angle in degrees).

breaking In v1.4.0, the 'children' prop changed from a render prop to a function child (children as a function). ↓

fix If you were passing React nodes directly, wrap them in a function that receives fill.

gotcha Requires react-native-svg to be installed and linked (react-native link react-native-svg) for iOS/Android. ↓

fix Install react-native-svg and run react-native link react-native-svg (for React Native < 0.60). For RN >= 0.60, autolinking should work.

Install

npm install react-native-circular-progress

yarn add react-native-circular-progress

pnpm add react-native-circular-progress

Imports

AnimatedCircularProgress

wrong

const AnimatedCircularProgress = require('react-native-circular-progress')

correct

import { AnimatedCircularProgress } from 'react-native-circular-progress'

Named export; no default export. Requires react-native-svg to be installed as a peer dependency.

CircularProgress

wrong

import CircularProgress from 'react-native-circular-progress'

correct

import { CircularProgress } from 'react-native-circular-progress'

Also a named export for non-animated version. Cannot be default imported.

Props (TypeScript)

import type { CircularProgressProps, AnimatedCircularProgressProps } from 'react-native-circular-progress'

TypeScript types are shipped; use type imports for type-checking props.

Quickstart

Basic usage of AnimatedCircularProgress with required props: size, width, fill, tintColor, and backgroundColor.

import React from 'react';
import { View } from 'react-native';
import { AnimatedCircularProgress } from 'react-native-circular-progress';

const App = () => (
  <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
    <AnimatedCircularProgress
      size={120}
      width={15}
      fill={100}
      tintColor="#00e0ff"
      onAnimationComplete={() => console.log('Animation complete')}
      backgroundColor="#3d5875"
    />
  </View>
);

export default App;