useDate
A ticking clock hook built on persian-date and persian-holidays. Returns the current date/time, a ready-to-render formatted string, individual calendar fields, and — when asked — whether today is a holiday.
Last updated August 12, 2026
Overview
Installation
$ npx shadcn@latest add https://ui.persian-labs.ir/r/use-date.jsonUsage
import { useDate } from "@/hooks/use-date"
function Clock() {
const date = useDate({ checkHoliday: true })
// null on the server and on the very first client render -- "now" can't be
// read consistently in both places, so the hook waits until it has mounted.
if (!date) return null
const { formatted, isHoliday } = date
return <span>{formatted}{isHoliday ? " (تعطیل)" : ""}</span>
}Examples
Gregorian mode
Set calendarType: "miladi" to switch the formatted output and returned fields to the Gregorian calendar.
Custom pattern & digits
pattern accepts any date-fns token, and digits lets you force Latin digits even in the shamsi calendar.
Disabling the tick
Pass interval: 0 to read the time once on mount without setting up a timer — useful for a one-shot timestamp.
Holiday flagging
checkHoliday: true flags the current date against the built-in Iranian holiday dataset and lists any matching entries.
Day/week/month/year navigator
A selected-date navigator built from persian-date's addDays/addWeeks/addMonths/addYears -- a common pattern for calendar/agenda UIs that step through time by different units.
RTL
The shamsi calendar's month and weekday names are already Persian, so a pattern like EEEE d MMMM yyyy reads naturally in right-to-left content.