Skip to main content

Directives

Svelte use: action factories for event tracking. Each factory takes an AnalyticsInstance, an event name, and optional default properties, then returns a Svelte action.

Setup​

Create directives once in a shared file:

// src/lib/analytics/directives.ts
import { analytics } from './analytics'
import {
  createTrackClickDirective,
  createTrackFormSubmitDirective,
  createTrackOutboundLinkDirective,
} from '@repo/analytics'

export const trackClick = createTrackClickDirective(analytics, 'clicked')
export const trackFormSubmit = createTrackFormSubmitDirective(analytics, 'form_submitted')
export const trackOutbound = createTrackOutboundLinkDirective(analytics, 'outbound_link')

createTrackClickDirective​

Tracks click events on any HTMLElement.

function createTrackClickDirective(
  analytics: AnalyticsInstance,
  eventName: string,
  properties?: Record<string, unknown>
): (node: HTMLElement, buttonProperties?: Record<string, unknown>) => { destroy: () => void }

Per-element properties are merged with default properties:

<script lang="ts">
  import { trackClick } from '$lib/analytics/directives'
</script>

<button use:trackClick={{ type: 'login' }}>Login</button>
<button use:trackClick={{ type: 'signup' }}>Sign Up</button>

createTrackFormSubmitDirective​

Tracks form submit events on HTMLFormElement.

function createTrackFormSubmitDirective(
  analytics: AnalyticsInstance,
  eventName: string,
  properties?: Record<string, unknown>
): (node: HTMLFormElement) => { destroy: () => void }
<script lang="ts">
  import { trackFormSubmit } from '$lib/analytics/directives'
</script>

<form use:trackFormSubmit>
  <input name="email" type="email" />
  <button type="submit">Submit</button>
</form>

createTrackOutboundLinkDirective​

Tracks clicks on HTMLAnchorElement nodes that point to external domains. Only fires when node.hostname !== window.location.hostname. Automatically includes the url property.

function createTrackOutboundLinkDirective(
  analytics: AnalyticsInstance,
  eventName: string,
  properties?: Record<string, unknown>
): (node: HTMLAnchorElement) => { destroy: () => void }
<script lang="ts">
  import { trackOutbound } from '$lib/analytics/directives'
</script>

<a href="https://example.com" use:trackOutbound>External Link</a>