https://github.com/vikramsamak/react-realtime-clock
A React component library with a real-time clock and essential hooks like `useTimeElapsed`, `useStopWatch`, and `useCountdown` for versatile time-tracking features.
https://github.com/vikramsamak/react-realtime-clock
clock component date library react typescript
Last synced: 9 months ago
JSON representation
A React component library with a real-time clock and essential hooks like `useTimeElapsed`, `useStopWatch`, and `useCountdown` for versatile time-tracking features.
- Host: GitHub
- URL: https://github.com/vikramsamak/react-realtime-clock
- Owner: vikramsamak
- License: mit
- Created: 2024-10-03T17:04:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-11T15:21:40.000Z (about 1 year ago)
- Last Synced: 2025-04-12T09:06:56.434Z (9 months ago)
- Topics: clock, component, date, library, react, typescript
- Language: TypeScript
- Homepage: https://storybook-react-realtime-clock.vercel.app/
- Size: 877 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-realtime-clock
A React component library with a real-time clock and essential hooks like useTimeElapsed, useStopWatch, and useCountdown for versatile time-tracking features.
## Table of Contents
- [Installation](#installation)
- [Tailwind CSS Support](#tailwind-css-support)
- [Usage](#usage)
- [Props](#props)
- [Examples](#examples)
- [Customization](#customization)
- [Hooks](#hooks)
- [License](#license)
## Installation
You can install the library using npm or yarn:
```bash
npm install react-realtime-clock
```
## Tailwind CSS Support
This library is styled using **Tailwind CSS**. To use the styles as intended, please ensure that Tailwind CSS is installed and configured in your project.
## Usage
Here’s how to use the `RealTimeClock` component in your application:
```tsx
import React from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
return (
);
};
export default App;
```
## Props
| Prop | Type | Default | Description |
|------------------------|---------------------|----------------|------------------------------------------------------------------------------------------------|
| `containerClassName` | `string` | `undefined` | Additional class names for the container element. |
| `clockTextClassName` | `string` | `undefined` | Additional class names for the clock text element. |
| `timeZone` | `TimezoneType` | `"UTC"` | Time zone for the clock (e.g., `"America/New_York"`). |
| `format` | `FormatType` | `"HH:mm:ss"` | Format for displaying the time (e.g., `"hh:mm:ss A"`). |
| `clockType` | `typeof DIGITAL_CLOCK_TYPE or typeof ANALOG_CLOCK_TYPE` |`DIGITAL_CLOCK_TYPE`| Specifies whether to display a digital or analog clock. |
| `clockSize` | `number` | `200` | Size of the analog clock in pixels. |
| `renderAnalogClockNumbers` | `boolean` | `true` | Indicates whether to display numbers on the analog clock. |
## Examples
This section provides various examples of how to use the `RealTimeClock` component in your React application.
### Example 1: Basic Clock
A simple example of a clock displaying the current time in UTC:
```tsx
import React from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
return (
);
};
export default App;
```
### Example 2: Clock with Custom Styles
Customize the appearance of the clock with additional class names:
```tsx
import React from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
return (
);
};
export default App;
```
### Example 3: Real-Time Clock with Different Time Zones
Display the clock with different time zones dynamically:
```tsx
import React, { useState } from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
const [timeZone, setTimeZone] = useState("Asia/Kolkata");
const [format, setFormat] = useState("hh:mm:ss A");
return (
setTimeZone(e.target.value)}>
UTC
Asia/Kolkata
America/New_York
Europe/Berlin
America/Los_Angeles
setFormat(e.target.value)}>
HH:mm:ss
hh:mm:ss A
MMMM Do YYYY, h:mm:ss a
MM/DD/YYYY, h:mm A
);
};
export default App;
```
### Example 4: Full Customization with Analog Clock
Combine all props for a fully customized analog clock experience:
```tsx
import React from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
return (
);
};
export default App;
```
## Customization
The `RealTimeClock` component offers various customization options, allowing you to tailor its appearance and functionality to fit your application’s design and requirements.
### 1. Styling the Clock
You can customize the appearance of the clock by using the following props:
- **`containerClassName`**: This prop allows you to add custom styles to the container of the clock. You can use any Tailwind CSS or custom class names here.
```tsx
```
### 2. Time Zone Selection
The clock supports various time zones, which you can set using the timeZone prop. This prop accepts any valid IANA time zone string.
Example of setting the time zone to America/New_York:
```tsx
```
### 3. Time Format
The format prop allows you to specify how the time should be displayed. You can use the following format strings:
- "HH:mm:ss": 24-hour format
- "hh:mm:ss A": 12-hour format with AM/PM
- "MMMM Do YYYY, h:mm:ss a": Full month name and year
- "MM/DD/YYYY, h:mm A": US date format
- "YYYY-MM-DD HH:mm:ss": ISO date format
- "HH:mm": Simple hour and minute
- "hh:mm A": Simple hour and minute with AM/PM
- "dddd, MMMM Do YYYY": Full weekday name, month, and year
Example of setting the format to a 12-hour clock:
```tsx
```
### 4. Clock Type
You can set the type of clock to either digital or analog using the clockType prop. You can also control the size of the analog clock using the clockSize prop.
Example of setting the clock to analog:
```tsx
```
### 5. Combining Customizations
You can combine the above customization options for a fully personalized clock display:
```tsx
import React from 'react';
import { RealTimeClock } from "react-realtime-clock";
const App = () => {
return (
);
};
export default App;
```
### 6. Responsive Design
The component is designed to be responsive. You can use Tailwind CSS utility classes to make it adapt to various screen sizes. For example, using responsive font sizes:
```tsx
```
## Hooks
### `useTimeElapsed`
The `useTimeElapsed` hook is a custom hook that calculates the elapsed time from a specified target date in a specific time zone. It provides the flexibility to start and stop the counting based on provided conditions.
### Example
```tsx
import { useTimeElapsed } from "react-realtime-clock";
const App = () => {
const timeElapsed = useTimeElapsed({
targetDate: "2000-02-22T00:00:00Z",
timeZone: "Asia/Kolkata",
countingConditions: {
startCondition: true,
stopCondition: false,
},
});
return
{timeElapsed};
};
```
#### Parameters
| Parameter | Type | Default | Description |
|----------------------|-------------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------|
| `targetDate` | `string or Date` | `undefined` | The date from which to calculate the elapsed time. |
| `timeZone` | `TimezoneType` | `"Asia/Kolkata"` | The time zone in which to calculate the elapsed time. |
| `countingConditions` | `{ startCondition: boolean, stopCondition: boolean }` | `{ startCondition: false, stopCondition: false }` | An object to control when to start and stop the counting. |
#### Returns
- `string`: A formatted string representing the elapsed time based on the target date and time zone.
## License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
### Summary of the MIT License
The MIT License is a permissive free software license that allows users to:
- Use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
- Allow others to do the same with their copies of the Software.
### Conditions
The only conditions are:
- The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software.
- The Software is provided "as is", without warranty of any kind. The authors are not liable for any damages or issues arising from its use.
### For More Information
For the full text of the MIT License, please see the [LICENSE](LICENSE) file in this repository.