use-favicon

Bind the page favicon 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 { useFavicon } from "@vizejs/composable/use-favicon";

Try it

Show build status in the tab icon

Swap the favicon to reflect state that the reader should notice from another tab.

Open the interactive example

What to observe: Build failed switches the tab icon to a red dot; Build passed switches it back to green.

Any URL works, including data URLs. The existing <link rel="icon"> is updated or created.

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 { useFavicon } from "@vizejs/composable/use-favicon";

const status = ref<"passing" | "failing">("passing");
const dot = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><circle cx="8" cy="8" r="7" fill="${color}"/></svg>`)}`;
useFavicon(computed(() => dot(status.value === "passing" ? "#16a34a" : "#dc2626")));
</script>

<template>
  <div class="composable-example">
    <p>Change the tab icon to reflect a build status.</p>
    <div class="example-actions">
      <button type="button" @click="() => (status = 'passing')">Build passed</button>
      <button type="button" @click="() => (status = 'failing')">Build failed</button>
    </div>
    <output aria-live="polite">Favicon shows the {{ status }} build.</output>
  </div>
</template>

Runtime contract

API

useFavicon

Bind the page favicon to reactive state. Every <link> whose rel contains rel (icon, shortcut icon, apple-touch-icon, …) gets baseUrl + icon as its href; when none exists, one <link rel="icon"> is created. Accepts a writable ref (used as-is), a getter (followed), a plain string, or nothing (an owned ref). Server rendering: this is a client-only side effect. The document is never touched on the server, and icon keeps its given value; emit the initial <link rel="icon"> through the application's head manager. Watchers are released with the owning reactive scope; the last icon stays.

function useFavicon( icon?: MaybeRefOrGetter<string | null | undefined>, options: UseFaviconOptions = {}, ): FaviconControls

const { icon } = useFavicon(() => (unread.value ? "/unread.svg" : "/icon.svg"));

Types

FaviconLink

<link> subset updated by useFavicon.

FaviconHost

Document capability used by useFavicon.

UseFaviconOptions

Options for useFavicon.

FaviconControls

Reactive state returned by useFavicon.