React Native Reanimated Timer

A Reanimated-powered library for creating smooth and customizable timers, stopwatches, and time displays in React Native. ⏳

Features

Features

• 🧩 Highly Composable – All components — Timer, Stopwatch, and Clock — are fully composable for complete flexibility.
• ⚡ High Performance – Achieves smooth 60 FPS animations powered by Reanimated.
• 🎨 Fully Customizable – Configure behavior, appearance, and animations through flexible props.
• 🎞️ Built-in Entry & Exit Animations – Seamlessly integrate with Reanimated transitions.
• 🧱 Powered by Reanimated – Built with Reanimated for smooth, performant, and reliable animations.
• 🎨 Supports className Prop – Works with NativeWind for Tailwind-style styling, and optionally uses tailwind-merge for intelligent class merging.
• 🚀 Expo-Compatible – Works out of the box with managed Expo projects.
• ✨ TypeScript First – Fully typed for an enhanced developer experience and safer code.

Components

• Timer – Countdown timer with customizable duration, animations, and callbacks. Check it out
• Stopwatch – Accurate stopwatch with start, pause, and reset controls. Check it out
• Digital Clock – Live clock display showing current time, updated in real-time. Check it out

Composability

All components — Timer, Stopwatch, and Clock — are now fully composable.

They share a common set of time unit segments: Day, Hour, Minute, Second, and Millisecond, AMPM.

This means you have full control over how time is displayed and animated. You can mix and match these building blocks to create custom layouts, animations, and styles that fit your app perfectly.

Example

import { Timer } from '@docren/react-native-reanimated-timer';

export default function App() {
  return (
    <Timer durationMs={60000}>
      <Timer.Minute />
      <Timer.Second />
      <Timer.Millisecond />
    </Timer>

    <Stopwatch autoStart>
      <Stopwatch.Hour />
      <Stopwatch.Minute />
      <Stopwatch.Second />
    </Stopwatch>

    <Clock format="12">
      <Clock.Hour />
      <Clock.Minute />
      <Clock.Second />
      <Clock.Millisecond />
      <Clock.AMPM />
    </Clock>
  );
}

Why Composability?

This design enables:

• 🧱 Maximum Flexibility – Use only the units you need (Minute, Second, etc.).
• 🎨 Full Customization – Add your own separators, labels, or styles between units.
• ⚙️ Consistency – All unit components share a consistent API across Timer, Stopwatch, and Clock.
• 🔄 Interchangeability – Swap components easily without changing the surrounding layout or logic.

Each component (Timer, Stopwatch, Clock) manages its own internal timing logic while exposing shared subcomponents for complete composability and freedom of use.

Learn more

Acknowledgements

• 🙏 Component and Animation Inspiration
  This library is heavily inspired by react-native-animated-stopwatch-timer and the accompanying blog. It’s a great resource for understanding animation patterns with Reanimated—highly recommended!

• 🧠 Custom Hook Design
  The internal time management logic is built on top of react-timer-hook, using it as a core dependency for reliable timekeeping. This allows leveraging its proven functionality while layering custom logic and controls tailored to the app’s specific needs.

  If you only need a headless timekeeping hook (without UI), you can use react-timer-hook directly.

Installation

npm install @docren/react-native-reanimated-timer

Note: This package is built on top of react-native-reanimated, so make sure it’s properly installed and configured in your project. Refer to the Reanimated installation guide if you haven’t already set it up.

Optional Peer Dependency

For better and more predictable class name merging, you can optionally install tailwind-merge >= 3.0.0:

npm install tailwind-merge

When twMerge={true}, the library uses tailwind-merge to intelligently combine class names. If tailwind-merge is not installed, it will gracefully fall back to the default behavior — the nearest className wins.

Usage

Check out this example Snack

Timer

Timer component that counts down from a specified duration.

Props

| Prop | Type | Default | Description | | ---------- | ---------- | --------- | ------------------------------------------------------ | | durationMs | number | - | Required The duration in milliseconds for the timer. | | intervalMs | number | 1000 | The interval in milliseconds to update the timer. | | autoStart | boolean | true | Whether to start the timer automatically. | | onExpire | () => void | undefined | Callback function to be called when the timer expires. |

For additional props, refer to the Common Props section.

Methods

start: () => void;

Starts the timer if it is not already running or paused.

timerRef.current?.start();

pause: () => void;

Pauses the timer if it is running.

timerRef.current?.pause();

resume: () => void;

Resumes the timer if it is paused.

timerRef.current?.resume();

restart: (duration: number; autoStart?: boolean) => void;

Restarts the timer with a new duration and optional autoStart value.

• duration - The new duration in milliseconds.
• autoStart - Whether to start the timer automatically. Optional, Defaults to true

timerRef.current?.restart(1800000, false); // Timer for 30 mins, with autoStart set to false

reset: () => void;

Resets the timer to the initial duration and intial autoStart value.

timerRef.current?.reset();

Stopwatch

Props

| Prop | Type | Default | Description | | --------------- | ------- | --------- | ----------------------------------------------------- | | autoStart | boolean | false | Whether to start the stopwatch automatically. | | intervalMs | number | 1000 | The interval in milliseconds to update the stopwatch. | | offsetTimestamp | Date | undefined | The offset timestamp to start the stopwatch from. |

For additional props, refer to the Common Props section.

Methods

start: () => void;

Starts the stopwatch

timerRef.current?.start();

pause: () => void;

Pauses the stopwatch

timerRef.current?.pause();

reset: (autoStart?: boolean, offset?: Date) => void;

Resets the stopwatch with a new offset and autoStart value.

• autoStart - Whether to start the timer automatically. Optional, Defaults to false
• offset - The offset date to set the stopwatch to. Optional, Defaults to undefined

timerRef.current?.restart();

Clock

Clock component to display the current time.

• It can be configured to show hours, minutes, seconds, and milliseconds.
• The time format can be set to either 12-hour or 24-hour format.

Props

| Prop | Type | Default | Description | | ---------- | ------------ | ------- | ------------------------------------------------- | | format | '12' | '24' | '24' | The time format to be used. | | intervalMs | number | 1000 | The interval in milliseconds to update the clock. |

For additional props, refer to the Common Props section.

Common Props

All common props are optional

| Prop | Type | Default | Description | | ----------------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | animationDelay | number | 0 | Delay before the animation starts (in milliseconds). | | animationDuration | number | 80 | Duration of the animation (in milliseconds). | | animationDistance | number | 1200 | Distance the animation moves. | | animationDirection | 'up' | 'down' | 'down' | Direction of the animation ('up' or 'down'). | | entering | EntryOrExitLayoutType | undefined | Custom entering animation from react-native-reanimated. | | exiting | EntryOrExitLayoutType | undefined | Custom exiting animation from react-native-reanimated . | | skipEntering | boolean | true | Useful for preventing initial animation on mount. | | skipExiting | boolean | false | Useful for preventing exit animation on unmount. | | twMerge | boolean | false | Uses tailwind-merge to merge classNames. | | style | ViewStyle | undefined | Style for the component. | | className | string | undefined | Styling for component. | | digitContainerStyle | ViewStyle | undefined | Style for grouped digit's container. eg: [tens of seconds, units of seconds] | | digitContainerClassName | string | undefined | Styling for digit's container | | digitStyle | TextStyle | undefined | Style for the individual digits, eg: Tens of seconds | | digitClassName | string | undefined | Styling the individual digits |

When twMerge={true}, the library uses tailwind-merge to intelligently combine class names. If tailwind-merge is not installed, it will gracefully fall back to the default behavior — the nearest className wins.

Segments

Each time unit is represented by an individual Segment component. These can be freely composed to control what parts of the time are displayed.

• Day (not available for Clock)
• Hour
• Minute
• Second
• Millisecond
• AM/PM (available only for Clock)

| Prop | Type | Default | Description | | -------------- | --------- | --------- | --------------------------------------- | | className | string | undefined | Styles the segment container | | style | ViewStyle | undefined | Inline styles for the segment container | | digitClassName | string | undefined | Styles applied to the individual digits | | digitStyle | TextStyle | undefined | Inline styles for the individual digits |

While each segment supports its own digitStyle and digitClassName, it’s generally recommended to define digitStyle at the root level. This ensures consistent styling across all segments for a unified look.

Related

• react-timer-hook
• react-native-animated-stopwatch-timer

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

This project is licensed under the MIT License.

MIT

Authors

• amilmohd155

Built with ❤️

• react-native-reanimated
• react-native-builder-bob