CWA 2.0 is in alpha: try it, build with it, give feedback. APIs can still change between releases; see Releases.

Utilities

useHtmlContent

Turn the links in API-provided HTML into client-side CwaLinks, and render the HTML with the v-cwa-html directive.

useHtmlContent makes the links in HTML from the API work like <NuxtLink>. After the component mounts, it replaces every <a> in a container with a <CwaLink>, so an internal link doesn't reload the page. It also returns vCwaHtml, a directive to use in place of v-html.

const container = ref<HTMLElement | null>(null)
const { vCwaHtml } = useHtmlContent(container, content)

<div ref="container" v-cwa-html="content" />

Signature

useHtmlContent(
  container: Ref<HTMLElement | null>,
  html?: MaybeRefOrGetter<string | undefined>
): { vCwaHtml: Directive }

Parameters

Parameter	Type	Description
`container`	`Ref<HTMLElement \| null>`	A template ref to the element that holds the HTML
`html`	`MaybeRefOrGetter<string \| undefined>`	The HTML source. Optional, but pass it: the links are converted again whenever it changes

Pass html. With only the container, the conversion runs again only when the element changes. HTML that changes while the same element stays mounted, such as an inline edit or a Mercure update, keeps its raw <a> tags, and those links reload the page.

Return Values

Return	Type	Purpose
`vCwaHtml`	`Directive`	Renders HTML like `v-html`, without redrawing it during hydration. Destructure it in `<script setup>` and use it as `v-cwa-html`. It isn't registered globally

How Links Are Converted

Each <a> with an href is replaced by a <CwaLink> mounted in a <span>. An <a> with no href is left alone.
An absolute URL on the site's own hostname becomes a path, so it navigates client-side. Any other absolute URL stays external and opens in a new tab.
An href that isn't a valid absolute URL and doesn't start with / is treated as a host, so about becomes //about. Write internal links as paths that start with /.
Every attribute except href and target is copied to the link. Prefetching is off.
The links are unmounted before each conversion and when the component unmounts.
It runs in the browser only, after mount. The server renders the original <a> tags.

Example

HTML Content shows a rich-text component that uses both the links and the directive, and explains why v-cwa-html is faster than v-html.

Resource Route

Resolve the URL path for a CWA resource — convert an IRI to the route it lives at.

State and a sign-in function for a custom login form, with a safe redirect after sign-in.