# react-use-clock

> React clock hook.

Latest version **2.0.0** (published 2026-06-02) · ISC license · 0 weekly downloads

## Install

```sh
npm install react-use-clock
pnpm add react-use-clock
yarn add react-use-clock
bun add react-use-clock
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-06-02 |
| First published | 2022-11-11 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 16.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 5 |
| Author | Filip Chalupa |
| Maintainers | onset |
| Keywords | clock, hook, time, typescript, react |

## Links

- npm: https://www.npmjs.com/package/react-use-clock
- Repository: https://github.com/FilipChalupa/react-use-clock
- Homepage: https://github.com/FilipChalupa/react-use-clock#readme
- Issues: https://github.com/FilipChalupa/react-use-clock/issues
- npm.io page: https://npm.io/package/react-use-clock

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-06-02
- 1.1.1 — 2024-05-16
- 1.1.0 — 2024-05-16
- 1.0.0 — 2023-12-08
- 0.2.0 — 2023-12-08
- 0.1.0 — 2023-12-08
- 0.0.4 — 2022-11-15
- 0.0.3 — 2022-11-11
- 0.0.2 — 2022-11-11
- 0.0.1 — 2022-11-11

## README

# React useClock [![npm](https://img.shields.io/npm/v/react-use-clock.svg)](https://www.npmjs.com/package/react-use-clock) ![npm type definitions](https://img.shields.io/npm/types/react-use-clock.svg)

Simplified access to current hours, minutes, seconds.

[![screencast](https://raw.githubusercontent.com/FilipChalupa/react-use-clock/HEAD/screencast.gif)](https://react-use-clock.netlify.app)

## Installation

```bash
npm install react-use-clock
```

## How to use

```jsx
import { useClock } from 'react-use-clock'

const MyClockComponent = () => {
	const clock = useClock()

	return (
		<div>
			<p>
				Time is:{' '}
				<strong>
					{clock.hours.toString().padStart(2, '0')}:
					{clock.minutes.toString().padStart(2, '0')}:
					{clock.seconds.toString().padStart(2, '0')}
				</strong>
			</p>
			<p>
				Date is:{' '}
				<strong>
					{clock.day}. {clock.month}. {clock.year}
				</strong>
			</p>
			<p>
				Using formatter:{' '}
				<strong>
					{clock.date.toLocaleTimeString('en', {
						day: 'numeric',
						month: 'long',
						year: 'numeric',
					})}
				</strong>
			</p>
			<div
				style={{
					'--hours': `${clock.hours}`,
					'--minutes': `${clock.minutes}`,
					'--seconds': `${clock.seconds}`,
				}}
			/>
		</div>
	)
}
```

Create your own wrapper component. You can get inspired by [Example here](src/stories/Example.tsx) and [Storybook here](https://react-use-clock.netlify.app).

## Granularity

By default the clock ticks every second. If you only display minutes, hours or
the date, pass a coarser `granularity` to avoid unnecessary re-renders – the
component then re-renders only once per chosen unit and the lower fields are
zeroed.

```jsx
// Re-renders once per minute, seconds are always 0.
const clock = useClock({ granularity: 'minute' })
```

Supported values: `'second'` (default), `'minute'`, `'hour'`, `'day'`.

```ts
useClock(options?: {
	granularity?: 'second' | 'minute' | 'hour' | 'day'
	initialValue?: ClockSnapshot // server snapshot / first render
	getDate?: () => Date // custom time source, e.g. for testing
})
```

> **Migrating from 1.x:** the hook now takes a single options object instead of
> positional arguments. Replace `useClock(initialValue, getDate)` with
> `useClock({ initialValue, getDate })`.

## Development

Run `npm start` and `npm run storybook` parallelly.

---
_Source: https://npm.io/package/react-use-clock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._