Skip to main content

​
Remaining Time

Calculate and format the remaining time until a future date with Persian output.

​
Basic Usage

import { remainingTime } from "@persian-tools/persian-tools";

const futureDate = new Date("2024-12-31T23:59:59");
const remaining = remainingTime(futureDate);

console.log(remaining);
// Output: { days: 78, hours: 13, minutes: 59, seconds: 59 }

​
API Reference

​
date
Date | number
required
Future date or timestamp
​
result
object
Object containing time components

​
Examples

​
Countdown Timer

import { remainingTime, digitsEnToFa } from "@persian-tools/persian-tools";

const displayCountdown = (targetDate: Date): string => {
	const time = remainingTime(targetDate);

	const days = digitsEnToFa(time.days.toString());
	const hours = digitsEnToFa(time.hours.toString());
	const minutes = digitsEnToFa(time.minutes.toString());

	return `${days} روز و ${hours} ساعت و ${minutes} دقیقه`;
};

const eventDate = new Date("2024-12-31T23:59:59");
console.log(displayCountdown(eventDate));
// "۷۸ روز و ۱۳ ساعت و ۵۹ دقیقه"

​
Event Countdown

import { remainingTime } from "@persian-tools/persian-tools";

const showEventCountdown = (eventDate: Date) => {
	const time = remainingTime(eventDate);

	if (time.days > 0) {
		return `${time.days} روز مانده`;
	} else if (time.hours > 0) {
		return `${time.hours} ساعت مانده`;
	} else {
		return `${time.minutes} دقیقه مانده`;
	}
};

​
Use Cases

Show countdown for flash sales:
const saleEnds = new Date('2024-10-20T23:59:59');
const countdown = remainingTime(saleEnds);
Display time until event registration closes:
const registrationDeadline = new Date('2024-11-01');
const remaining = remainingTime(registrationDeadline);

​
Type Definition

interface RemainingTime {
	days: number;
	hours: number;
	minutes: number;
	seconds: number;
}

function remainingTime(date: Date | number): RemainingTime;