Skip to main content

useScheduledDate

This hook returns the moment the frame is scheduled to be displayed.

Frames are prepared shortly before they go on display, which spreads the work out instead of letting every frame be built at once. The clock is moved forward to match, so new Date() and Date.now() already give the moment the frame is seen, and a widget never needs this hook to get it. Use it when you want your code to say plainly that it shows the frame's display time.

Import​

import { useScheduledDate } from "~lib/use-scheduled-date";

API​

const scheduledDate = useScheduledDate();

Parameters​

This hook takes no parameters.

Return Value​

NameTypeDescription
scheduledDateDateThe moment the frame is scheduled to be displayed

A date is always returned. In the studio preview, and whenever a frame is prepared for immediate display, the current time is returned — for those the two are the same moment.

The clock keeps running from the display moment while the widget renders, so new Date() read later in the render sits a few seconds past this value. This hook gives the exact scheduled moment.

The same instance is returned on every render, so it is safe to use in a dependency list.

Example​

import { useScheduledDate } from "~lib/use-scheduled-date";
import { useTimeZone } from "~lib/use-time-zone";

const Widget = () => {
  const scheduledDate = useScheduledDate();
  const timeZone = useTimeZone();

  const time = scheduledDate.toLocaleTimeString(undefined, {
    timeZone,
    hour: "2-digit",
    minute: "2-digit",
  });

  const date = scheduledDate.toLocaleDateString(undefined, {
    timeZone,
    weekday: "long",
    month: "long",
    day: "numeric",
  });

  return (
    <div className="flex h-full w-full flex-col items-center justify-center">
      <h1 className="text-6xl">{time}</h1>
      <p className="text-2xl">{date}</p>
    </div>
  );
};

Anything derived from "today" can be measured from this value too:

import { useScheduledDate } from "~lib/use-scheduled-date";

const Widget = () => {
  const scheduledDate = useScheduledDate();

  const daysUntil = Math.ceil(
    (new Date("2030-01-01").getTime() - scheduledDate.getTime()) / 86_400_000,
  );

  return <h1>{daysUntil} days to go</h1>;
};

See Also​