use-favicon

Bind the page favicon to reactive state.


Package	`@vizejs/composable/use-favicon`
Own the source	`vize lib pull composable:use-favicon`
Runtime exports	`useFavicon`
Gzip budget	1792 B

Usage

import { useFavicon } from "@vizejs/composable/use-favicon";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useFavicon`	dom	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	`useMounted`

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.

Member	Type	Description
`rel`	`string`	Link relation.
`href`	`string`	Icon URL.

`FaviconHost`

Document capability used by useFavicon.

Member	Type	Description
`findIcons`	`(rel: string) => Iterable<FaviconLink>`	Find every `<link>` whose `rel` contains `rel`.
`createIcon`	`(rel: string) => FaviconLink`	Create (and attach to `<head>`) a new `<link rel={rel}>`.

`UseFaviconOptions`

Options for useFavicon.

Member	Type	Description
`baseUrl`?	`string`	Prefix prepended to every icon value.
`rel`?	`string`	Link relation matched (substring) and used for created links.
`host`?	`MaybeRefOrGetter<FaviconHost \| null \| undefined>`	Document capability for alternate runtimes and tests.

`FaviconControls`

Reactive state returned by useFavicon.

Member	Type	Description
`icon`	`Ref<string \| null \| undefined>`	Icon URL (before `baseUrl`). Writable; `null`/`undefined` leaves the current icons untouched. When a getter was passed, the next getter change overwrites manual assignments.
`supported`	`ComputedRef<boolean>`	Whether a document capability is attached. Inside a component it stays `false` until mounted, so hydration matches the server render.