Scripts

Carbon Ads

Carbon Ads is an ad service that provides a performance friendly way to show ads on your site.

Nuxt Scripts provides a headless <ScriptCarbonAds> component to embed Carbon Ads in your Nuxt app.

Carbon Ads

Nuxt Config Setup

The simplest way to load Carbon Ads globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the useScriptCarbonAds composable.

export default defineNuxtConfig({
  scripts: {
    registry: {
      carbonAds: true
    }
  }
})

useScriptCarbonAds()

The useScriptCarbonAds composable lets you have fine-grain control over when and how Carbon Ads is loaded on your site.

const { proxy } = useScriptCarbonAds()

// ad slots render automatically

Please follow the Registry Scripts guide to learn more about advanced usage.

First-Party Mode

This script supports First-Party Mode which is auto-enabled, routing all traffic through your domain for improved privacy and ad blocker bypass.

export default defineNuxtConfig({
  scripts: {
    registry: {
      carbonAds: true
    }
  }
})

Example

Using Carbon Ads only in production while using the proxy to send events.

<script setup lang="ts">
const { proxy } = useScriptCarbonAds()

// noop in development, ssr
// just works in production, client
function handleAction() {
  // ad slots render automatically
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

`<ScriptCarbonAds>`

The <ScriptCarbonAds> component works differently to other Nuxt Scripts component and does not rely on useScript(), instead it simply inserts a script tag into the div of the component on mount.

By default, the component uses CarbonAds best practices which is to load immediately on mount. You can make use of Element Event Triggers if you want to load the ads on a specific event.

<template>
  <ScriptCarbonAds
    serve="..."
    placement="..."
    format="..."
  />
</template>

Handling Ad-blockers

You can use these hooks to add a fallback when CarbonAds is blocked.

<template>
  <ScriptCarbonAds
    serve="..."
    placement="..."
    format="..."
  >
    <template #error>
      <!-- Fallback ad -->
      Please support us by disabling your ad blocker.
    </template>
  </ScriptCarbonAds>
</template>

Adding UI

The component renders as headless, meaning there is no inherit styles. If you'd like to customize the look of the ad, you can use this example from nuxt.com.

<template>
  <ScriptCarbonAds
    class="Carbon border border-gray-200 dark:border-gray-800 rounded-lg bg-white dark:bg-white/5"
    serve="..."
    placement="..."
    format="..."
  />
</template>

<style lang="postcss">
/* Credits to nuxt.com */
.dark .Carbon {
  min-height: 220px;
  .carbon-text {
    @apply text-gray-400;

    &:hover {
      @apply text-gray-200;
    }
  }
}

.light .Carbon {
  .carbon-text {
    @apply text-gray-600;

    &:hover {
      @apply text-gray-800;
    }
  }
}

.Carbon {
  @apply p-3 flex flex-col max-w-full;

  @screen sm {
    @apply max-w-xs;
  }

  @screen lg {
    @apply mt-0;
  }

  #carbonads span {
    @apply flex flex-col justify-between;

    .carbon-wrap {
      @apply flex flex-col;

      flex: 1;

      @media (min-width: 320px) {
        @apply flex-row;
      }

      @screen lg {
        @apply flex-col;
      }

      .carbon-img {
        @apply flex items-start justify-center mb-4;

        @media (min-width: 320px) {
          @apply mb-0;
        }

        @screen lg {
          @apply mb-4;
        }
      }

      .carbon-text {
        @apply flex-1 text-sm w-full m-0 text-left block;

        &:hover {
          @apply no-underline;
        }

        @media (min-width: 320px) {
          @apply ml-4;
        }

        @screen lg {
          @apply ml-0;
        }
      }
    }
  }

  img {
    @apply w-full;
  }

  & .carbon-poweredby {
    @apply ml-2 text-xs text-right text-gray-400 block pt-2;

    &:hover {
      @apply no-underline text-gray-500;
    }
  }
}
</style>

Component API

See the Facade Component API for full props, events, and slots.

Note: The Carbon Ads script does not extend the useScript() composable. Accessing the script will return the HTMLScriptElement.

servestring required

placementstring required

formatstring required

triggerElementScriptTrigger

Defines the trigger event to load the script.

Edit this page

Markdown For LLMs

Bluesky Embed

Server-side rendered Bluesky embeds with zero client-side API calls.

Clarity

Use Clarity in your Nuxt app.