useHeadSafe

The recommended way to provide head data with user input.

Usage

The useHeadSafe composable is a wrapper around the useHead composable that restricts the input to only allow safe values. This is the recommended way to manage head data when working with user input, as it prevents XSS attacks by sanitizing potentially dangerous attributes.

When using useHeadSafe, potentially dangerous attributes like innerHTML in scripts or http-equiv in meta tags are automatically stripped out to prevent XSS attacks. Use this composable whenever you’re working with user-generated content.

Parameters

input · MaybeComputedRef<HeadSafe> · required

A MaybeComputedRef<HeadSafe> object containing head data. You can pass all the same values as useHead, but only safe attributes will be rendered.

Return Values

This composable does not return any value.

Allowed Attributes

The following attributes are whitelisted for each head element type:

const WhitelistAttributes = {
  htmlAttrs: ['class', 'style', 'lang', 'dir'],
  bodyAttrs: ['class', 'style'],
  meta: ['name', 'property', 'charset', 'content', 'media'],
  noscript: ['textContent'],
  style: ['media', 'textContent', 'nonce', 'title', 'blocking'],
  script: ['type', 'textContent', 'nonce', 'blocking'],
  link: [
    'color',
    'crossorigin',
    'fetchpriority',
    'href',
    'hreflang',
    'imagesrcset',
    'imagesizes',
    'integrity',
    'media',
    'referrerpolicy',
    'rel',
    'sizes',
    'type'
  ],
}

Example

[app/pages/user-profile.vue]

<script setup lang="ts">
// User-generated content that might contain malicious code
const userBio = ref('<script>alert("xss")<' + '/script>')

useHeadSafe({
  title: `User Profile`,
  meta: [
    {
      name: 'description',
      content: userBio.value, // Safely sanitized
    },
  ],
})
</script>

Type

export function useHeadSafe (
  input: MaybeComputedRef<HeadSafe>
): void