Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection, RequestResponseExamples } from "@wix/docs-ui/content";

{/* Generated by @wix/tw-typedoc-to-wix-docs from packages/site-service-head-appender/src/definition/index.ts. Do not edit this file directly — edit the TSDoc in the source package. */}

# Head Appender Functions

## setHead()

Adds HTML to the head of the page.

Use it for markup that has to be in the head before the page renders, such as preload links and
styles. Call it while the page renders on the server, so the markup is in the page's HTML. Markup
added in the browser might not reach the page.

Throws when `content` contains a script tag, including encoded forms such as `&lt;script` or
`%3Cscript`. The check matches anywhere in the string, including attribute values and CSS text,
and ignores case. It removes control characters before matching, so a script tag split by a
control character, such as a null byte, still throws. When it throws, it adds nothing.

Adds the content as is. Apart from the script tag check, it doesn't escape or validate anything.
The service passes every call on to the host and has no method to remove content, so add each
piece of content once.

### Method Declaration

```ts
setHead(content: string, type?: HeadContentType): void
```

### Method Parameters

<PropertyList bordered>
  <Property name="content" type="string" required>
    HTML to add to the head, such as one or more `<link>`, `<meta>`, or `<style>`
    elements. Escape any values you build into it.

    Can't contain a script tag.
  </Property>
  <Property name="type" type="HeadContentType">
    Type of head content, which the host uses to decide where to place it.

    Content of the default type reaches only search engine crawlers, not site visitors' browsers. For
    content that every site visitor's page needs, such as preload links and styles, specify
    `HeadContentType.GENERAL`.

    Default: `HeadContentType.AFTER_SECURITY`
    <ExpandableSection name="Enum Values">
      <PropertyList>
        <Property name="'after_security'">
          Markup that the host places after its security-related head content. It's the default type for `setHead()`.
        </Property>
        <Property name="'general'">
          General head markup, such as preload links and styles. Use it for content that every site visitor's page needs.
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>

### Examples

<RequestResponseExamples defaultName="setHead" requestName="JavaScript" requestType="JavaScript" examples={[
  {
    title: `Preload a font while the page renders on the server`,
    content: {
      methodExample: {
        Request: `~~~tsx
import { useService } from '@wix/services-manager-react'
import { HeadAppenderDefinition } from '@wix/site-service-head-appender/definition'
import { HeadContentType } from '@wix/site-service-head-appender/types'
import { RenderingContextDefinition } from '@wix/site-service-rendering-context/definition'

const FONT_URL = 'https://static.example.com/fonts/brand.woff2'

function BrandHeading({ text }: { text: string }) {
    const headAppenderService = useService(HeadAppenderDefinition)
    const renderingContextService = useService(RenderingContextDefinition)

    // Add the link to the page's HTML, so the browser fetches the font while it parses the page.
    if (renderingContextService.SSR) {
        headAppenderService.setHead(
            \`<link rel="preload" href="\${FONT_URL}" as="font" type="font/woff2" crossorigin>\`,
            HeadContentType.GENERAL,
        )
    }

    return <h1 className="brand-heading">{text}</h1>
}
~~~`
      }
    }
  },
  {
    title: `Add styles that contain script-like text`,
    content: {
      methodExample: {
        Request: `~~~ts
// \`\\3c \` is the CSS escape for \`<\`, so the CSS keeps its meaning but passes the script tag check.
const escapedCss = css.replace(/<script/gi, '\\\\3c script')

// A closing style tag would end the element early, and the browser would read the rest as HTML.
// So cut the CSS where the first one starts.
const end = escapedCss.search(/<[/]style(?=[\\t\\n\\f\\r />])/i)
const safeCss = end === -1 ? escapedCss : escapedCss.slice(0, end)

try {
    headAppenderService.setHead(\`<style>\${safeCss}</style>\`, HeadContentType.GENERAL)
} catch {
    // The CSS contains an encoded script tag, such as \`&lt;script\`. The page renders without it.
}
~~~`
      }
    }
  }
]} />