# useDocumentTitle

> Keeps document.title in sync with a value, SSR-safe.

- Category: Effects
- Package: `hookli` (install with `npm i hookli`)
- Docs: https://hookli.vercel.app/docs/use-document-title

## Signature

```ts
useDocumentTitle(title: string, options?: UseDocumentTitleOptions): void
```

## Parameters

- `title`: `string` — The document title to apply. Written to document.title in a layout effect on the client and skipped during server rendering.
- `options`: `UseDocumentTitleOptions` (default: `{}`) — Behaviour options (see below).

## Types

### UseDocumentTitleOptions

Options controlling unmount behaviour.

- `preserveTitleOnUnmount`: `boolean` (default: `true`) — When false, the title captured on mount is restored when the component unmounts. Defaults to true, which leaves the title in place.

## Usage

```tsx
import { useDocumentTitle } from "hookli";

export function Demo() {
  useDocumentTitle("Dashboard — hookli", {
    preserveTitleOnUnmount: false,
  });

  return <h1>Dashboard</h1>;
}
```

## Source

`src/hooks/use-document-title/use-document-title.ts`

```ts
import { useRef } from "react";
import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
import { useUnmount } from "../use-unmount/use-unmount";

interface UseDocumentTitleOptions {
  preserveTitleOnUnmount?: boolean;
}

export const useDocumentTitle = (
  title: string,
  options: UseDocumentTitleOptions = {},
) => {
  const { preserveTitleOnUnmount = true } = options;
  const defaultTitle = useRef<string | null>(null);

  useIsomorphicLayoutEffect(() => {
    defaultTitle.current = window.document.title;
  }, []);

  useIsomorphicLayoutEffect(() => {
    window.document.title = title;
  }, [title]);

  useUnmount(() => {
    if (!preserveTitleOnUnmount && defaultTitle.current !== null) {
      window.document.title = defaultTitle.current;
    }
  });
};
```