> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Head Scripts

> Add tracking pixels, analytics, or custom code to your link surveys for self-hosted instances.

Custom Head Scripts allow you to inject custom HTML code into the `<head>` section of your **Link Surveys**. This is useful for adding tracking pixels, analytics scripts, chatbots, or any other third-party code.

> [!NOTE]
>
> Custom Head Scripts is only available for **Link Surveys on self-hosted instances**. This feature is not available for Website & App Surveys or on Formbricks Cloud.

## When to Use Custom Head Scripts

Use Custom Head Scripts when you need to:

* Add analytics tools (Google Analytics, Plausible, Mixpanel, etc.)
* Integrate tracking pixels (Facebook Pixel, LinkedIn Insight Tag, etc.)
* Include custom JavaScript for advanced survey behavior
* Add third-party widgets or chatbots
* Inject custom meta tags or stylesheets

## Configuration Guide

### Workspace-Level Scripts

These scripts apply to **all link surveys** in your workspace.

![Custom Scripts in Workspace Settings](https://mintcdn.com/formbricks/fuXjoDPfwirx9kHD/images/surveys/link-surveys/custom-head-scripts/workspace-setting.webp?fit=max\&auto=format\&n=fuXjoDPfwirx9kHD\&q=85\&s=b76058034aa95704ebbbb2c90d08a25d)

**1. Navigate to Settings → Workspace → General**

Go to **Settings → Workspace → General** from the main navigation menu.

**2. Locate Custom Scripts Section**

Scroll down to the **Custom Scripts** card on the General page.

**3. Add Your Scripts**

Paste your HTML code into the text area. You can include:

* `<script>` tags (inline or with `src` attribute)
* `<meta>` tags
* `<link>` tags for stylesheets
* `<style>` tags
* `<noscript>` tags

**Example:**

```html theme={null}
<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

**4. Save Your Changes**

Click the **Save** button to apply your custom scripts to all link surveys.

### Survey-Level Scripts

Override or extend workspace scripts for **specific surveys**.

![Custom HTML tab in the Distribute modal](https://mintcdn.com/formbricks/fuXjoDPfwirx9kHD/images/surveys/link-surveys/custom-head-scripts/share-survey-modal-setting.webp?fit=max\&auto=format\&n=fuXjoDPfwirx9kHD\&q=85\&s=d978e6012cf87f7b91c2a02c78885256)

**1. Open the Distribute modal**

Navigate to your survey and click **Distribute** to open the Distribute modal.

**2. Go to Custom HTML Tab**

In the Distribute modal, click on the **Custom HTML** tab under **Distribution settings**.

**3. Choose Script Mode**

Select how you want survey scripts to interact with workspace scripts:

* **Add to Workspace Scripts** - Survey scripts will be added **after** workspace scripts (both run)
* **Replace Workspace Scripts** - Survey scripts will **replace** workspace scripts entirely (only survey scripts run)

**4. Add Survey-Specific Scripts**

Paste your HTML code into the "Survey Scripts" text area.

**Example** (Facebook Pixel for a specific campaign):

```html theme={null}
<!-- Facebook Pixel for Campaign X -->
<script>
  fbq('track', 'ViewContent', {
    content_name: 'Customer Satisfaction Survey',
    campaign: 'Q1-2024'
  });
</script>
```

**5. Save Changes**

Click **Save** to apply the survey-specific scripts.

## To keep in mind

> [!WARNING]
>
> Custom scripts execute in the context of your survey pages. Only add scripts from trusted sources. Malicious scripts could compromise your survey data or user privacy.

* **Scripts Don't Load in Preview Mode** — Custom Head Scripts are not loaded in preview mode (editor preview or `?preview=true`). This prevents analytics tracking and pixel triggers during testing. To test your scripts, activate your survey and view it through the actual link survey URL without the preview parameter.

* **Link Surveys Only** — Custom Head Scripts only work with link surveys. They are not available for app/website surveys, as those are embedded in your application and should use your application's existing script management.

* **Self-Hosted Only** — This feature is only available on self-hosted instances. Formbricks Cloud does not support Custom Head Scripts for security and performance reasons.

* **Permissions** — Only Owners, Managers, and members with Manage access can configure Custom Head Scripts.

## Common Use Cases

### Global Analytics (Workspace Level)

Set up Google Analytics for all surveys in your workspace:

```html theme={null}
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

### Campaign-Specific Tracking (Survey Level with Add Mode)

Add Facebook Pixel tracking for a specific marketing campaign:

**Workspace Scripts:** Google Analytics (as above)

**Survey Scripts:**

```html theme={null}
<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', 'YOUR_PIXEL_ID');
  fbq('track', 'PageView');
</script>
```

**Result:** Both Google Analytics and Facebook Pixel run on this survey.

### Custom Fonts (Workspace Level)

Load custom fonts for all your surveys:

```html theme={null}
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
  body {
    font-family: 'Inter', sans-serif;
  }
</style>
```

## Troubleshooting

If your scripts aren't loading, check:

1. **Is it a self-hosted instance?** Custom scripts only work on self-hosted Formbricks.
2. **Are you in preview mode?** Scripts don't load in preview—test with the actual survey link.
3. **Check the browser console** for JavaScript errors that might prevent script execution.
4. **Verify your HTML syntax** is correct (properly closed tags, valid attributes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.