use-document-title

Bind the document title to reactive state.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useDocumentTitle } from "@vizejs/composable/use-document-title";

Try it

Show an unread count in the tab title

Keep the document title in sync with application state.

Open the interactive example

What to observe: Receive message twice and the tab title becomes (2) Inbox. Mark all read restores Inbox.

The title accepts a ref, getter or computed. When the component unmounts, the previous title is restored by default.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed, ref } from "vue";
import { useDocumentTitle } from "@vizejs/composable/use-document-title";

const unread = ref(0);
useDocumentTitle(computed(() => (unread.value > 0 ? `(${unread.value}) Inbox` : "Inbox")));
</script>

<template>
  <div class="composable-example">
    <p>Show the unread count in the browser tab title.</p>
    <div class="example-actions">
      <button type="button" @click="() => (unread += 1)">Receive message</button>
      <button type="button" @click="() => (unread = 0)">Mark all read</button>
    </div>
    <output aria-live="polite">{{ unread }} unread</output>
  </div>
</template>

Runtime contract

API

useDocumentTitle

Bind the document title to reactive state. Accepts a writable ref (used as-is), a getter (followed), a plain string, or nothing (an owned ref seeded from the current title). Every non-nullish title is passed through template before it is written. With observe, external title changes flow back into title. Server rendering: the document is never touched and title keeps the value it was given (or undefined). Head management for server-rendered markup (<title> in the HTML) is the job of the application's head manager; this composable only updates the live document on the client. Watchers and the observer are released with the owning reactive scope, which also applies restoreOnDispose.

function useDocumentTitle( title?: MaybeRefOrGetter<string | null | undefined>, options: UseDocumentTitleOptions = {}, ): DocumentTitleControls

const { title } = useDocumentTitle(() => route.meta.title, { template: "%s | Vize" });

Types

DocumentTitleHost

Document subset used by useDocumentTitle.

UseDocumentTitleOptions

Options for useDocumentTitle.

DocumentTitleControls

Reactive state returned by useDocumentTitle.