⬅️ Back to Table of Contents

📄 useTemporalNow

📊 Analysis Summary

Metric	Count
🔧 Functions	13
📦 Imports	6
🟢 Vue Composition API	1
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useTemporalNow/index.ts

📦 Imports

Name	Source
Pausable	@vueuse/shared
Ref	vue
ConfigurableScheduler	../_configurable
shallowRef	vue
watch	vue
useRafFn	../useRafFn

---

Vue Composition API

Name	Type	Reactive Variables	Composables
watch	watch	none	none

---

Functions

useTemporalNow(options: UseTemporalNowOptions): UseTemporalNowReturn

Reactive Temporal API with timezone and calendar support.

Parameters:

• options any: Configuration options

See: https://vueuse.org/useTemporalNow

Raw JSDoc

/**
 * Reactive Temporal API with timezone and calendar support.
 *
 * @see https://vueuse.org/useTemporalNow
 * @param options - Configuration options
 */

Calls:

• assertTemporal
• resolveTemporal
• shallowRef (from vue)
• TemporalImpl.Now.zonedDateTimeISO(timezone.value).withCalendar
• scheduler
• watch (from vue)
• now.value.withTimeZone
• now.value.withCalendar
• now.value.toPlainDate
• now.value.toPlainTime
• now.value.toPlainDateTime
• now.value.toLocaleString
• now.value.add
• now.value.subtract
• TemporalImpl.ZonedDateTime.compare

Internal Comments:

// Update immediately when timezone/calendar change, rather than waiting for the next tick (x3)

Code

export function useTemporalNow(options: UseTemporalNowOptions = {}): UseTemporalNowReturn {
  const {
    timezone: initialTimezone = 'UTC',
    calendar: initialCalendar = 'gregory',
    scheduler = useRafFn,
    temporal: customTemporal,
  } = options

  const TemporalImpl = assertTemporal(resolveTemporal(customTemporal))

  const timezone = shallowRef(initialTimezone)
  const calendar = shallowRef(initialCalendar)

  const now = shallowRef(
    TemporalImpl.Now.zonedDateTimeISO(timezone.value).withCalendar(calendar.value),
  )

  function updateNow() {
    now.value = TemporalImpl.Now.zonedDateTimeISO(timezone.value).withCalendar(calendar.value)
  }

  const { isActive, pause, resume } = scheduler(updateNow)

  // Update immediately when timezone/calendar change, rather than waiting for the next tick
  watch([timezone, calendar], updateNow)

  const toTimezone = (tz: string) => now.value.withTimeZone(tz)
  const toCalendar = (cal: string) => now.value.withCalendar(cal)
  const toPlainDate = () => now.value.toPlainDate()
  const toPlainTime = () => now.value.toPlainTime()
  const toPlainDateTime = () => now.value.toPlainDateTime()
  const format = (formatOptions?: Intl.DateTimeFormatOptions) => now.value.toLocaleString(undefined, formatOptions)
  const add = (duration: Temporal.DurationLike) => now.value.add(duration)
  const subtract = (duration: Temporal.DurationLike) => now.value.subtract(duration)
  const compare = (other: Temporal.ZonedDateTime | string) => TemporalImpl.ZonedDateTime.compare(now.value, other)

  return {
    now,
    timezone,
    calendar,
    toTimezone,
    toCalendar,
    toPlainDate,
    toPlainTime,
    toPlainDateTime,
    format,
    add,
    subtract,
    compare,
    isActive,
    pause,
    resume,
  }
}

resolveTemporal(custom: typeof Temporal): typeof Temporal | undefined

Parameters:

• custom typeof Temporal

Returns: typeof Temporal | undefined

Code

function resolveTemporal(custom?: typeof Temporal): typeof Temporal | undefined {
  if (custom)
    return custom
  return typeof Temporal === 'undefined' ? undefined : Temporal
}

assertTemporal(impl: typeof Temporal | undefined): typeof Temporal

Parameters:

• impl typeof Temporal | undefined

Returns: typeof Temporal

Code

function assertTemporal(impl: typeof Temporal | undefined): typeof Temporal {
  if (!impl)
    throw new Error('[VueUse] No `Temporal` implementation found. See https://vueuse.org/useTemporalNow for details.')
  return impl
}

Internal helpers

Declared inside another function in this file.

updateNow(): void

Returns: void

Calls:

• TemporalImpl.Now.zonedDateTimeISO(timezone.value).withCalendar

Code

function updateNow() {
    now.value = TemporalImpl.Now.zonedDateTimeISO(timezone.value).withCalendar(calendar.value)
  }

toTimezone(tz: string): any

Parameters:

• tz string

Returns: any

Calls:

• now.value.withTimeZone

Code

(tz: string) => now.value.withTimeZone(tz)

toCalendar(cal: string): any

Parameters:

• cal string

Returns: any

Calls:

• now.value.withCalendar

Code

(cal: string) => now.value.withCalendar(cal)

toPlainDate(): any

Returns: any

Calls:

• now.value.toPlainDate

Code

() => now.value.toPlainDate()

toPlainTime(): any

Returns: any

Calls:

• now.value.toPlainTime

Code

() => now.value.toPlainTime()

toPlainDateTime(): any

Returns: any

Calls:

• now.value.toPlainDateTime

Code

() => now.value.toPlainDateTime()

format(formatOptions: Intl.DateTimeFormatOptions): any

Parameters:

• formatOptions Intl.DateTimeFormatOptions

Returns: any

Calls:

• now.value.toLocaleString

Code

(formatOptions?: Intl.DateTimeFormatOptions) => now.value.toLocaleString(undefined, formatOptions)

add(duration: Temporal.DurationLike): any

Parameters:

• duration Temporal.DurationLike

Returns: any

Calls:

• now.value.add

Code

(duration: Temporal.DurationLike) => now.value.add(duration)

subtract(duration: Temporal.DurationLike): any

Parameters:

• duration Temporal.DurationLike

Returns: any

Calls:

• now.value.subtract

Code

(duration: Temporal.DurationLike) => now.value.subtract(duration)

compare(other: Temporal.ZonedDateTime | string): any

Parameters:

• other Temporal.ZonedDateTime | string

Returns: any

Calls:

• TemporalImpl.ZonedDateTime.compare

Code

(other: Temporal.ZonedDateTime | string) => TemporalImpl.ZonedDateTime.compare(now.value, other)

---

Interfaces

UseTemporalNowOptions

Interface Code

export interface UseTemporalNowOptions extends ConfigurableScheduler {
  /**
   * Initial timezone
   *
   * @default 'UTC'
   */
  timezone?: string
  /**
   * Calendar system to use
   *
   * @default 'gregory'
   */
  calendar?: string
  /**
   * Custom `Temporal` implementation to use, e.g. the `Temporal` export from
   * `@js-temporal/polyfill` or another polyfill, instead of relying on the
   * global `Temporal` object.
   *
   * @default globalThis.Temporal
   */
  temporal?: typeof Temporal
}

Properties

Name	Type	Optional	Description
timezone	string	✓	not shown
calendar	string	✓	not shown
temporal	typeof Temporal	✓	not shown

UseTemporalNowReturn

Interface Code

export interface UseTemporalNowReturn extends Pausable {
  /**
   * Current `Temporal.ZonedDateTime`
   */
  now: Ref<Temporal.ZonedDateTime>
  /**
   * Current timezone
   */
  timezone: Ref<string>
  /**
   * Current calendar
   */
  calendar: Ref<string>
  /**
   * Convert to a different timezone
   */
  toTimezone: (timezone: string) => Temporal.ZonedDateTime
  /**
   * Convert to a different calendar
   */
  toCalendar: (calendar: string) => Temporal.ZonedDateTime
  /**
   * Get the `Temporal.PlainDate` (date only)
   */
  toPlainDate: () => Temporal.PlainDate
  /**
   * Get the `Temporal.PlainTime` (time only)
   */
  toPlainTime: () => Temporal.PlainTime
  /**
   * Get the `Temporal.PlainDateTime` (local date/time)
   */
  toPlainDateTime: () => Temporal.PlainDateTime
  /**
   * Format the current date/time
   */
  format: (options?: Intl.DateTimeFormatOptions) => string
  /**
   * Add a duration
   */
  add: (duration: Temporal.DurationLike) => Temporal.ZonedDateTime
  /**
   * Subtract a duration
   */
  subtract: (duration: Temporal.DurationLike) => Temporal.ZonedDateTime
  /**
   * Compare with another date/time
   */
  compare: (other: Temporal.ZonedDateTime | string) => number
}

Properties

Name	Type	Optional	Description
now	Ref<Temporal.ZonedDateTime>	✗	not shown
timezone	Ref<string>	✗	not shown
calendar	Ref<string>	✗	not shown
toTimezone	(timezone: string) => Temporal.ZonedDateTime	✗	not shown
toCalendar	(calendar: string) => Temporal.ZonedDateTime	✗	not shown
toPlainDate	() => Temporal.PlainDate	✗	not shown
toPlainTime	() => Temporal.PlainTime	✗	not shown
toPlainDateTime	() => Temporal.PlainDateTime	✗	not shown
format	(options?: Intl.DateTimeFormatOptions) => string	✗	not shown
add	(duration: Temporal.DurationLike) => Temporal.ZonedDateTime	✗	not shown
subtract	(duration: Temporal.DurationLike) => Temporal.ZonedDateTime	✗	not shown
compare	(other: Temporal.ZonedDateTime \| string) => number	✗	not shown

---

Generated by Syntax Scribe