---
title: "Custom Head Scripts"
description: "Add tracking pixels, analytics, or custom code to your link surveys for self-hosted instances."
icon: "code"
---

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.
</Note>

## 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.

<Frame>
  <img src="/images/xm-and-surveys/surveys/link-surveys/custom-head-scripts/workspace-setting.webp" alt="Custom Scripts in Workspace Settings" />
</Frame>

<Steps>
  <Step title="Navigate to Workspace Settings">
    Go to your Workspace Settings from the main navigation menu.
  </Step>

  <Step title="Locate Custom Scripts Section">
    Scroll down to the **Custom Scripts** card in the General settings.
  </Step>

  <Step title="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
    <!-- 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>
    ```
  </Step>

  <Step title="Save Your Changes">
    Click the **Save** button to apply your custom scripts to all link surveys.
  </Step>
</Steps>

### Survey-Level Scripts

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

<Frame>
  <img src="/images/xm-and-surveys/surveys/link-surveys/custom-head-scripts/share-survey-modal-setting.webp" alt="Custom HTML tab in Share Survey Modal" />  
</Frame>

<Steps>
  <Step title="Open Share Survey Modal">
    Navigate to your survey and click the **Share** button to open the share modal.
  </Step>

  <Step title="Go to Custom HTML Tab">
    In the share modal, click on the **Custom HTML** tab under the "Share Settings" section.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Add Survey-Specific Scripts">
    Paste your HTML code into the "Survey Scripts" text area.
    
    **Example** (Facebook Pixel for a specific campaign):
    
    ```html
    <!-- Facebook Pixel for Campaign X -->
    <script>
      fbq('track', 'ViewContent', {
        content_name: 'Customer Satisfaction Survey',
        campaign: 'Q1-2024'
      });
    </script>
    ```
  </Step>

  <Step title="Save Changes">
    Click **Save** to apply the survey-specific scripts.
  </Step>
</Steps>


## 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.
</Warning>

- **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, publish 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
<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
<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
<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).
