Logo
Docs

Svelte Integration Guide

Add Heyo live chat to your Svelte application with minimal overhead. SvelteKit compatible.
Try Heyo for Svelte →

This guide shows you how to add Heyo to your Svelte application. Works with Svelte and SvelteKit.

Installation

Method 1: JavaScript SDK (Recommended)

Install the SDK:

npm install @heyo.so/js

Then initialize it in your root component or +layout.svelte (SvelteKit):

<script>
  import { onMount } from 'svelte';
  import HEYO from '@heyo.so/js'; // or: import { HEYO } from '@heyo.so/js'

  onMount(() => {
    HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
  });
</script>

<slot />

Method 2: Script Tag in Component

Load the script dynamically:

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    const script = document.createElement('script');
    script.src = 'https://heyo.so/embed/script';
    script.defer = true;
    script.setAttribute('data-project-id', 'YOUR_PROJECT_ID');
    document.head.appendChild(script);

    return () => {
      document.head.removeChild(script);
    };
  });
</script>

SvelteKit Integration

Add to Root Layout

Create or update src/routes/+layout.svelte:

<script>
  import { onMount } from 'svelte';
  import HEYO from '@heyo.so/js'; // or: import { HEYO } from '@heyo.so/js'
  import { browser } from '$app/environment';

  onMount(() => {
    if (browser) {
      HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
    }
  });
</script>

<slot />

Advanced Usage

Create a Chat Store

Create src/lib/stores/chat.js:

import { writable } from 'svelte/store';

function createChatStore() {
  const { subscribe, set } = writable(false);

  return {
    subscribe,
    show: () => {
      window.HEYO?.show();
      set(true);
    },
    hide: () => {
      window.HEYO?.hide();
      set(false);
    },
    toggle: () => {
      window.HEYO?.toggle();
      set(!get(this));
    }
  };
}

export const chat = createChatStore();

Usage in a component:

<script>
  import { chat } from '$lib/stores/chat';
</script>

<button on:click={chat.show}>Need Help?</button>

Custom Chat Action

Create a Svelte action for chat control:

// src/lib/actions/chat.js
export function chatTrigger(node) {
  function handleClick() {
    window.HEYO?.show();
  }

  node.addEventListener('click', handleClick);

  return {
    destroy() {
      node.removeEventListener('click', handleClick);
    }
  };
}

Usage:

<script>
  import { chatTrigger } from '$lib/actions/chat';
</script>

<button use:chatTrigger>Open Chat</button>

Pass User Data

<script>
  import { onMount } from 'svelte';
  import HEYO from '@heyo.so/js'; // or: import { HEYO } from '@heyo.so/js'
  import { user } from '$lib/stores/user';

  $: if ($user && typeof window !== 'undefined') {
    HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: $user.name,
        email: $user.email
      }
    });
  }

  onMount(() => {
    HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
  });
</script>

Route-Based Control (SvelteKit)

<script>
  import { page } from '$app/stores';
  import { onMount } from 'svelte';

  $: {
    if (typeof window !== 'undefined') {
      // Hide on checkout page
      if ($page.url.pathname.includes('/checkout')) {
        window.HEYO?.hide();
      } else {
        window.HEYO?.show();
      }
    }
  }

  onMount(() => {
    HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
  });
</script>

TypeScript Support

For TypeScript projects, add type definitions in src/app.d.ts:

declare global {
  interface Window {
    HEYO: {
      init: (config: { projectId: string; user?: any }) => void;
      show: () => void;
      hide: () => void;
      toggle: () => void;
    };
  }
}

export {};

Best Practices

  • Use onMount to ensure browser environment
  • Check for browser in SvelteKit before accessing window
  • Initialize in root layout for site-wide availability
  • Leverage Svelte stores for reactive chat state
  • Use actions for reusable chat interactions

Troubleshooting

Widget not appearing

  • Ensure you're calling init in onMount
  • Check that you're in browser environment
  • Verify Project ID is correct

SSR errors in SvelteKit

  • Always check for browser before accessing window
  • Use onMount which only runs on client-side

Type errors

  • Add type definitions to src/app.d.ts
  • Use @heyo.so/js package for built-in types

Next Steps

Squarespace Integration Guide

Add Heyo live chat to your Squarespace website. Perfect for creatives, photographers, and agencies.

Vue.js Integration Guide

Add Heyo live chat to your Vue.js application with support for Vue 2, Vue 3, and Composition API.