useDocumentTitle

1"use client"
2 
3import * as React from "react"
4 
5export interface UseDocumentTitleOptions {
6  /** Restore `document.title` to the snapshot taken at mount when unmounting. Defaults to `true`. */
7  restoreOnUnmount?: boolean
8}
9 
10/**
11 * Sets `document.title` to `title` and keeps it in sync on every change. At mount
12 * the title as it stands **at that instant** is snapshotted into a ref; at unmount
13 * it is restored from that snapshot when `restoreOnUnmount` (default `true`), and
14 * left at the last title this hook wrote when `false`.
15 *
16 * `document` is only read and written inside effects — never during render or on
17 * the server — so the hook is safe in server-rendered components.
18 *
19 * Nested instances (say a route layout and a page component that both call it):
20 * each instance only remembers the title that was on the page when *it* mounted,
21 * and knows nothing about the others. Mount order decides what you see — the one
22 * that mounts last writes `document.title` last, so it wins. But if unmount order
23 * isn't strictly last-in-first-out (an outer instance unmounting before an inner
24 * one), the snapshot the outer instance restores is older than the title the inner
25 * one set, and the title "jumps back" further than expected instead of to the
26 * enclosing title. That is deliberate, simplified semantics, not a bug — when you
27 * genuinely need strict restore ordering across levels, use one shared title stack
28 * rather than several independent hook instances (see Customization levers in the
29 * docs).
30 */
31export function useDocumentTitle(
32  title: string,
33  options: UseDocumentTitleOptions = {},
34): void {
35  const { restoreOnUnmount = true } = options
36  const restoreOnUnmountRef = React.useRef(restoreOnUnmount)
37  const previousTitleRef = React.useRef<string | null>(null)
38 
39  // Keep restoreOnUnmountRef on the latest option — the unmount cleanup runs once
40  // and must read the current value, not the one closed over at mount.
41  React.useEffect(() => {
42    restoreOnUnmountRef.current = restoreOnUnmount
43  }, [restoreOnUnmount])
44 
45  // Snapshot the title at mount and restore it at unmount; empty deps so it fires
46  // once on a real mount/unmount instead of re-snapshotting on every title change.
47  React.useEffect(() => {
48    previousTitleRef.current = document.title
49    return () => {
50      if (restoreOnUnmountRef.current && previousTitleRef.current !== null) {
51        document.title = previousTitleRef.current
52      }
53    }
54  }, [])
55 
56  React.useEffect(() => {
57// … truncated