Lightweight React/React Native Countdown Circle Timer


React/React Native countdown timer component in a circle shape with color and progress animation.

react countdown

  • Countdown animation independently optimized for the Web and Mobile
  • Transition between colors during the countdown
  • Fully customizable content in the center of the circle
  • a11y support
  • Built-in and ready-to-use TypeScript type definitions.


yarn add react-countdown-circle-timer


Check out the full documentation for demos and use cases.

React Native

yarn add react-native-countdown-circle-timer


This component has a peer dependency on react-native-svg. Read the full documentation for the installation guide, as well as demos and use cases.

Props for both React/React Native

durationnumberrequiredCountdown duration in seconds
colors[color HEX: string, transition duration: number 0 ~ 1][]requiredArray of tuples: 1st param – color in HEX format; 2nd param – time to transition to next color represented as a fraction of the total duration
initialRemainingTimenumberSets the initial remaining time when the countdown starts. By default the countdown starts at the duration provided.
sizenumber180Width and height of the SVG element
strokeWidthnumber12Path stroke width
strokeLinecapround | squareroundPath stroke line cap
trailColorstring#d9d9d9Circle trail color – takes any valid color format (HEX, rgb, rgba, etc.)
rotationclockwise | counterclockwiseclockwiseProgress path rotation direction
isPlayingbooleanfalsePlay and pause animation
* isLinearGradientbooleanfalse* Apples linear gradient on top of the circle. The gradient doesn’t follow the circle path. Works best with two colors.
gradientUniqueKeystringUnique ID for the linearGradient element. It takes random ID if it’s not provided.
childrenReactNode | function({ remainingTime: number, elapsedTime: number }): number|string|ReactNodeRender function or component to customize the time/content in the center of the circle. The content is centered using flexbox.
onCompletefunction(totalElapsedTime: number): void | [shouldRepeat: boolean, delay: number]On complete handler. It can be used to repeat the countdown by returning an array where the first element shouldRepeat indicates if the loop should start over and second element delay specifies the delay before looping again in milliseconds. The callback receives as an argument the total elapsed time in seconds.
ariaLabelstringCountdown timerAria label for the whole component
renderAriaTimefunction({ remainingTime: number, elapsedTime: number }): stringRender prop function to customize the text message that will be read by the screen reader during the countdown.


About: Aakash Kothari

I am passionate about my work. Because I love what I do, I have a steady source of motivation that drives me to do my best. In my last job, this passion led me to challenge myself daily and learn new skills that helped me to do better work

    Leave a Reply

    %d bloggers like this: