Skip to content

A React library to synchronize timers across an application

License

Notifications You must be signed in to change notification settings

peterjuras/react-time-sync

Repository files navigation

react-time-sync

npm (scoped) Actions Status codecov Renovate semantic-release

A React library to synchronize timers across an application. Requires React v16.8 or higher.

Watch my talk from React Day Berlin to understand why you might need it.

Example

Usage

useCountdown hook

A custom hook which returns the time left until a certain millisecond UTC timestamp is reached

Example:

import { useCountdown } from "react-time-sync";

const MyComponent = ({ until }) => {
  const timeLeft = useCountdown({ until });
  return <div>{timeLeft > 0 ? `${timeLeft} seconds left` : "Done!"}</div>;
};

Input

The useCountdown hook expects an object with the following properties as the single argument:

until - A UTC millisecond timestamp until when the countdown should run (default: 0)

interval - one of TimeSync.SECONDS, TimeSync.MINUTES, TimeSync.HOURS, TimeSync.DAYS (default: TimeSync.SECONDS)

useTime hook

A custom hook which returns the current time rounded to the specified interval

Example:

import { useTime } from "react-time-sync";

const MyComponent = () => {
  const currentTime = useTime();
  return <div>{`The current time is: ${currentTime}`}</div>;
};

Input

The useTime hook expects an object with the following properties as the single argument:

unit - The number of units of interval (default: 1)

interval - one of TimeSync.SECONDS, TimeSync.MINUTES, TimeSync.HOURS, TimeSync.DAYS (default: TimeSync.SECONDS)

Countdown

A component that accepts render props to periodically re-render its children with the time left until a certain millisecond UTC timestamp

Example:

import { Countdown } from 'react-time-sync';

const MyComponent = ({ until }) => {
  return (
    <Countdown until={until}>
      {({ timeLeft }) => (
        <div>{timeLeft > 0 ? `${timeLeft} seconds left` : 'Done!'}</div>
      )}
    </Countdown>
  )
}

const until = Date.now() + 5000;

ReactDOM.render(<MyComponent until={until} />, ...);

Props

until - A UTC millisecond timestamp until when the countdown should run (required)

interval - one of TimeSync.SECONDS, TimeSync.MINUTES, TimeSync.HOURS, TimeSync.DAYS (default: TimeSync.SECONDS)

Timed

A component that accepts render props to periodically re-render its children with the current time rounded to the specified interval

Example:

import { Timed } from "react-time-sync";

const MyComponent = () => {
  return (
    <Timed>
      {({ currentTime }) => <div>{`The current time is: ${currentTime}`}</div>}
    </Timed>
  );
};

Props

unit - The number of units of interval (default: 1)

interval - one of TimeSync.SECONDS, TimeSync.MINUTES, TimeSync.HOURS, TimeSync.DAYS (default: TimeSync.SECONDS)

connectTime()()

A higher order component meant to be used in combination with redux.

Example:

import { connectTime, SECONDS } from "react-time-sync";

const timeSlotsSelector = createSelector(
  (currentTime) => currentTime,
  (currentTime) => [currentTime - 1, currentTime + 1],
);

function mapStateToProps({ currentTime }) {
  const timeSlots = timeSlotSelectors(currentTime);
  return {
    timeSlots,
  };
}

const timerConfig = {
  unit: 1,
  interval: SECONDS,
};

export default connectTime(timerConfig)(connect(mapStateToProps)(MyComponent));

timerConfig properties

unit - The number of units of interval (default: 1)

interval - one of TimeSync.SECONDS, TimeSync.MINUTES, TimeSync.HOURS, TimeSync.DAYS (default: TimeSync.SECONDS)

TimeProvider

You can use a <TimeProvider> component to use a custom instance of TimeSync, e.g. when you want to synchronize timers across your application

Example:

import { useState } from "react";
import { TimeProvider } from "react-time-sync";
import TimeSync from "time-sync";

const App = ({ children }) => {
  const [timeSync] = useState(() => new TimeSync());
  return (
    <div>
      <TimeProvider timeSync={timeSync}>{children}</TimeProvider>
    </div>
  );
};

Props

timeSync - A custom TimeSync instance that should be passed down with the context. (default: new TimeSync())