@gfazioli/mantine-clock
Version:
React Clock components and hooks for Mantine with timezone support, countdown timers, customization options, and real-time updates.
107 lines (106 loc) • 4.01 kB
TypeScript
/**
* Options for configuring the `useClockCountDown` hook.
*/
export interface UseClockCountDownOptions {
/** Whether the countdown is active and updating. */
enabled?: boolean;
/** The timezone to use for the countdown calculations. */
timezone?: string;
/** The frequency (in milliseconds) at which the countdown updates. */
updateFrequency?: number;
/** Whether to use 24-hour format or 12-hour format. */
use24Hours?: boolean;
/** Whether to pad single-digit seconds with a leading zero. */
padSeconds?: boolean;
/** Whether to pad single-digit minutes with a leading zero. */
padMinutes?: boolean;
/** Whether to pad single-digit hours with a leading zero. */
padHours?: boolean;
/** Target date for the countdown (Date object or ISO string). */
targetDate?: Date | string;
/** Number of hours to count down from current time. */
hours?: number;
/** Number of minutes to count down from current time. */
minutes?: number;
/** Number of seconds to count down from current time. */
seconds?: number;
/** Callback function called when countdown reaches zero. */
onCountDownCompleted?: () => void;
}
/**
* Data returned by the `useClockCountDown` hook.
*/
export interface ClockCountDownData {
/** The remaining years. */
year: number;
/** The remaining months (1-12). */
month: number;
/** The remaining days. */
day: number;
/** The remaining weeks. */
week: number;
/** Whether the current year is a leap year (based on target date). */
isLeap: boolean;
/** The remaining hours (adjusted for 12/24-hour format). */
hours: number | string;
/** The remaining minutes. */
minutes: number | string;
/** The remaining seconds. */
seconds: number | string;
/** The remaining milliseconds. */
milliseconds: number;
/** Whether the time is AM or PM (only relevant if use24Hours is false). */
amPm?: 'AM' | 'PM';
/** Whether the countdown has completed (reached zero). */
isCompleted: boolean;
/** Whether the countdown is currently running. */
isRunning: boolean;
/** Total remaining time in milliseconds. */
totalMilliseconds: number;
/** Start the countdown */
start: () => void;
/** Pause/stop the countdown */
pause: () => void;
/** Reset the countdown to initial values */
reset: () => void;
/** Resume the countdown from current position */
resume: () => void;
}
/**
* `useClockCountDown` is a React hook that provides real-time countdown data.
*
* This hook allows you to create a countdown timer to a specific date or time duration.
* You can specify either a target date or a duration (hours, minutes, seconds) from the current time.
* The hook returns an object containing detailed countdown information and supports timezone,
* update frequency, and 12/24-hour format options.
*
* @param {UseClockCountDownOptions} options - Configuration options for the countdown.
* @returns {ClockCountDownData} An object containing the current countdown data.
*
* @example
* // Countdown to a specific date
* const { hours, minutes, seconds, isCompleted } = useClockCountDown({
* targetDate: '2024-12-31T23:59:59Z',
* timezone: 'America/New_York',
* onCountDownCompleted: () => console.log('Happy New Year!'),
* });
*
* @example
* // Countdown for 12 hours from now
* const { hours, minutes, seconds } = useClockCountDown({
* hours: 12,
* updateFrequency: 1000,
* use24Hours: false,
* });
*
* @example
* // Countdown for 30 minutes and 45 seconds
* const countdown = useClockCountDown({
* minutes: 30,
* seconds: 45,
* padHours: true,
* padMinutes: true,
* padSeconds: true,
* });
*/
export declare function useClockCountDown({ enabled, timezone, updateFrequency, use24Hours, padSeconds, padMinutes, padHours, targetDate, hours, minutes, seconds, onCountDownCompleted, }: UseClockCountDownOptions): ClockCountDownData;