Vue.js Integration

Integrate the hiroi agent widget into your Vue.js application using components and composition API.

Quick Start

Get your Site ID from the Integration tab in the dashboard:

The Integration tab provides your Site ID and ready-to-use embed code.

Installation

No npm package needed - the widget loads from a CDN. You just need Vue:

npm install vue

Basic Component (Options API)

Create a ChatWidget.vue component:

<!-- src/components/ChatWidget.vue -->
<template>
  <!-- Widget renders itself into the DOM -->
</template>

<script>
export default {
  name: 'ChatWidget',
  props: {
    siteId: {
      type: String,
      default: null
    },
    sessionToken: {
      type: String,
      default: null
    }
  },
  mounted() {
    // Create script element
    const script = document.createElement('script');
    script.src = 'https://hiroi.ai/widget.js';
    script.async = true;

    // Set auth attribute (session token takes priority)
    if (this.sessionToken) {
      script.setAttribute('data-session-token', this.sessionToken);
    } else if (this.siteId) {
      script.setAttribute('data-site-id', this.siteId);
    }

    // Append to document
    document.body.appendChild(script);

    // Store reference for cleanup
    this.$_widgetScript = script;
  },
  beforeUnmount() {
    // Destroy widget instance and cleanup script
    if (window.VAWaveWidget) {
      window.VAWaveWidget.destroy();
    }
    if (this.$_widgetScript && document.body.contains(this.$_widgetScript)) {
      document.body.removeChild(this.$_widgetScript);
    }
  }
};
</script>

Usage

<!-- src/App.vue -->
<template>
  <div id="app">
    <h1>My Vue App</h1>
    <p>Agent widget appears in the bottom-right corner.</p>

    <ChatWidget site-id="YOUR_SITE_UUID" />
  </div>
</template>

<script>
import ChatWidget from './components/ChatWidget.vue';

export default {
  name: 'App',
  components: {
    ChatWidget
  }
};
</script>

Composition API (Vue 3)

Modern approach using Vue 3 Composition API:

<!-- src/components/ChatWidget.vue -->
<template>
  <!-- Widget renders itself -->
</template>

<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';

const props = defineProps({
  siteId: {
    type: String,
    default: null
  },
  sessionToken: {
    type: String,
    default: null
  },
  botName: {
    type: String,
    default: null
  },
  position: {
    type: String,
    default: 'bottom-right',
    validator: (value) => ['bottom-right', 'bottom-left', 'top-right', 'top-left'].includes(value)
  },
  size: {
    type: Number,
    default: 72
  },
  primaryColor: {
    type: String,
    default: '#8b5cf6'
  },
  bgColor: {
    type: String,
    default: '#0c0e14'
  },
  ringColor: {
    type: String,
    default: '#ffffff'
  },
  dynamicVariables: {
    type: Object,
    default: null
  }
});

const scriptRef = ref(null);

onMounted(() => {
  // Create script element
  const script = document.createElement('script');
  script.src = 'https://hiroi.ai/widget.js';
  script.async = true;

  // Set auth attribute (session token takes priority)
  if (props.sessionToken) {
    script.setAttribute('data-session-token', props.sessionToken);
  } else if (props.siteId) {
    script.setAttribute('data-site-id', props.siteId);
  }

  // Set configuration attributes
  if (props.botName) script.setAttribute('data-bot-name', props.botName);
  script.setAttribute('data-position', props.position);
  script.setAttribute('data-size', props.size.toString());
  script.setAttribute('data-primary-color', props.primaryColor);
  script.setAttribute('data-bg-color', props.bgColor);
  script.setAttribute('data-ring-color', props.ringColor);

  // Set dynamic variables if provided
  if (props.dynamicVariables) {
    script.setAttribute('data-dynamic-variables', JSON.stringify(props.dynamicVariables));
  }

  // Append to document
  document.body.appendChild(script);
  scriptRef.value = script;
});

onBeforeUnmount(() => {
  // Destroy widget instance and cleanup script
  if (window.VAWaveWidget) {
    window.VAWaveWidget.destroy();
  }
  if (scriptRef.value && document.body.contains(scriptRef.value)) {
    document.body.removeChild(scriptRef.value);
  }
});
</script>

Usage with Props

<!-- src/App.vue -->
<template>
  <div>
    <h1>Welcome to Our Site</h1>

    <ChatWidget
      site-id="YOUR_SITE_UUID"
      bot-name="Support Agent"
      position="bottom-right"
      :size="80"
      primary-color="#7c3aed"
      :dynamic-variables="{
        user_name: 'Sarah',
        membership: 'Premium',
        last_login: new Date().toISOString()
      }"
    />
  </div>
</template>

<script setup>
import ChatWidget from './components/ChatWidget.vue';
</script>

Create a reusable composable for programmatic control. The widget exposes itself as window.VAWaveWidget:

// src/composables/useChatWidget.js
import { ref, onMounted, onUnmounted } from 'vue';

export function useChatWidget() {
  const isReady = ref(false);
  let checkInterval = null;

  onMounted(() => {
    // Poll for widget readiness since the widget auto-initializes
    checkInterval = setInterval(() => {
      if (window.VAWaveWidget) {
        isReady.value = true;
        clearInterval(checkInterval);
        checkInterval = null;
      }
    }, 200);
  });

  onUnmounted(() => {
    if (checkInterval) {
      clearInterval(checkInterval);
    }
  });

  const openChat = () => {
    if (window.VAWaveWidget) {
      window.VAWaveWidget.activateChat();
    }
  };

  const closeChat = () => {
    if (window.VAWaveWidget) {
      window.VAWaveWidget.closeChat();
    }
  };

  const activateVoice = () => {
    if (window.VAWaveWidget) {
      window.VAWaveWidget.activateVoice();
    }
  };

  const destroy = () => {
    if (window.VAWaveWidget) {
      window.VAWaveWidget.destroy();
    }
  };

  return {
    isReady,
    openChat,
    closeChat,
    activateVoice,
    destroy
  };
}

Usage

<template>
  <div>
    <h1>Product Page</h1>

    <button
      @click="handleSupportClick"
      :disabled="!isReady"
      class="support-button"
    >
      Need Help?
    </button>

    <ChatWidget site-id="YOUR_SITE_UUID" />
  </div>
</template>

<script setup>
import { useChatWidget } from '@/composables/useChatWidget';
import ChatWidget from '@/components/ChatWidget.vue';

const { isReady, openChat } = useChatWidget();

const handleSupportClick = () => {
  openChat();
};
</script>

Vue Router Integration

Load widget conditionally based on route:

<!-- src/App.vue -->
<template>
  <div id="app">
    <RouterView />

    <!-- Only show on specific routes -->
    <ChatWidget
      v-if="showWidget"
      site-id="YOUR_SITE_UUID"
    />
  </div>
</template>

<script setup>
import { computed } from 'vue';
import { useRoute } from 'vue-router';
import ChatWidget from './components/ChatWidget.vue';

const route = useRoute();

// Show widget on product and support pages
const showWidget = computed(() => {
  return route.path.startsWith('/products') || route.path.startsWith('/support');
});
</script>

Vuex/Pinia Integration

Pass user state from store to widget:

With Pinia (Vue 3)

// src/stores/user.js
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    id: null,
    name: null,
    email: null,
    membership: null
  }),
  actions: {
    async fetchUser() {
      const response = await fetch('/api/user');
      const data = await response.json();
      this.id = data.id;
      this.name = data.name;
      this.email = data.email;
      this.membership = data.membership;
    }
  }
});

<!-- src/App.vue -->
<template>
  <div v-if="user.id">
    <h1>Welcome, {{ user.name }}!</h1>

    <ChatWidget
      site-id="YOUR_SITE_UUID"
      bot-name="Personal Agent"
      :dynamic-variables="{
        user_id: user.id,
        user_name: user.name,
        user_email: user.email,
        membership_level: user.membership
      }"
    />
  </div>
  <div v-else>Loading...</div>
</template>

<script setup>
import { onMounted } from 'vue';
import { storeToRefs } from 'pinia';
import { useUserStore } from '@/stores/user';
import ChatWidget from '@/components/ChatWidget.vue';

const userStore = useUserStore();
const { id, name, email, membership } = storeToRefs(userStore);

const user = { id, name, email, membership };

onMounted(() => {
  userStore.fetchUser();
});
</script>

With Vuex (Vue 2/3)

// src/store/index.js
import { createStore } from 'vuex';

export default createStore({
  state: {
    user: null
  },
  mutations: {
    setUser(state, user) {
      state.user = user;
    }
  },
  actions: {
    async fetchUser({ commit }) {
      const response = await fetch('/api/user');
      const data = await response.json();
      commit('setUser', data);
    }
  }
});

<!-- src/App.vue -->
<template>
  <div v-if="user">
    <h1>Welcome, {{ user.name }}!</h1>

    <ChatWidget
      site-id="YOUR_SITE_UUID"
      :dynamic-variables="{
        user_id: user.id,
        user_name: user.name,
        user_email: user.email
      }"
    />
  </div>
</template>

<script>
import { mapState, mapActions } from 'vuex';
import ChatWidget from './components/ChatWidget.vue';

export default {
  components: { ChatWidget },
  computed: {
    ...mapState(['user'])
  },
  methods: {
    ...mapActions(['fetchUser'])
  },
  mounted() {
    this.fetchUser();
  }
};
</script>

TypeScript Support (Vue 3)

Add TypeScript types for better developer experience:

// src/types/chat-widget.ts
export interface ChatWidgetProps {
  siteId?: string;
  sessionToken?: string;
  botName?: string;
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  size?: number;
  primaryColor?: string;
  bgColor?: string;
  ringColor?: string;
  dynamicVariables?: Record<string, string | number | boolean>;
}

export interface VAWaveWidgetAPI {
  activateChat: () => void;
  activateVoice: () => void;
  closeChat: () => void;
  toggle: () => void;
  stop: () => void;
  destroy: () => void;
}

declare global {
  interface Window {
    VAWaveWidget?: VAWaveWidgetAPI;
  }
}

Typed Component

<!-- src/components/ChatWidget.vue -->
<template>
  <!-- Widget renders itself -->
</template>

<script setup lang="ts">
import { onMounted, onBeforeUnmount, ref } from 'vue';
import type { ChatWidgetProps } from '@/types/chat-widget';

const props = withDefaults(defineProps<ChatWidgetProps>(), {
  siteId: undefined,
  sessionToken: undefined,
  botName: undefined,
  position: 'bottom-right',
  size: 72,
  primaryColor: '#8b5cf6',
  bgColor: '#0c0e14',
  ringColor: '#ffffff',
  dynamicVariables: undefined
});

const scriptRef = ref<HTMLScriptElement | null>(null);

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://hiroi.ai/widget.js';
  script.async = true;

  if (props.sessionToken) {
    script.setAttribute('data-session-token', props.sessionToken);
  } else if (props.siteId) {
    script.setAttribute('data-site-id', props.siteId);
  }

  if (props.botName) script.setAttribute('data-bot-name', props.botName);
  script.setAttribute('data-position', props.position);
  script.setAttribute('data-size', props.size.toString());
  script.setAttribute('data-primary-color', props.primaryColor);
  script.setAttribute('data-bg-color', props.bgColor);
  script.setAttribute('data-ring-color', props.ringColor);

  if (props.dynamicVariables) {
    script.setAttribute('data-dynamic-variables', JSON.stringify(props.dynamicVariables));
  }

  document.body.appendChild(script);
  scriptRef.value = script;
});

onBeforeUnmount(() => {
  if (window.VAWaveWidget) {
    window.VAWaveWidget.destroy();
  }
  if (scriptRef.value && document.body.contains(scriptRef.value)) {
    document.body.removeChild(scriptRef.value);
  }
});
</script>

Typed Composable

// src/composables/useChatWidget.ts
import { ref, onMounted, onUnmounted, type Ref } from 'vue';

interface UseChatWidgetReturn {
  isReady: Ref<boolean>;
  openChat: () => void;
  closeChat: () => void;
  activateVoice: () => void;
  destroy: () => void;
}

export function useChatWidget(): UseChatWidgetReturn {
  const isReady = ref(false);
  let checkInterval: ReturnType<typeof setInterval> | null = null;

  onMounted(() => {
    checkInterval = setInterval(() => {
      if (window.VAWaveWidget) {
        isReady.value = true;
        if (checkInterval) clearInterval(checkInterval);
        checkInterval = null;
      }
    }, 200);
  });

  onUnmounted(() => {
    if (checkInterval) clearInterval(checkInterval);
  });

  const openChat = () => {
    window.VAWaveWidget?.activateChat();
  };

  const closeChat = () => {
    window.VAWaveWidget?.closeChat();
  };

  const activateVoice = () => {
    window.VAWaveWidget?.activateVoice();
  };

  const destroy = () => {
    window.VAWaveWidget?.destroy();
  };

  return {
    isReady,
    openChat,
    closeChat,
    activateVoice,
    destroy
  };
}

Testing with Vue Test Utils

Test your ChatWidget component:

// src/components/ChatWidget.test.js
import { mount } from '@vue/test-utils';
import ChatWidget from './ChatWidget.vue';

describe('ChatWidget', () => {
  afterEach(() => {
    // Remove any scripts added during tests
    const scripts = document.querySelectorAll('script[data-site-id]');
    scripts.forEach(script => script.remove());
  });

  it('should render without crashing', () => {
    const wrapper = mount(ChatWidget, {
      props: { siteId: 'test-uuid' }
    });
    expect(wrapper.exists()).toBe(true);
  });

  it('should add script to document body', () => {
    mount(ChatWidget, {
      props: { siteId: 'test-uuid' }
    });

    const script = document.querySelector('script[data-site-id="test-uuid"]');
    expect(script).toBeTruthy();
    expect(script.src).toContain('widget.js');
  });

  it('should set configuration attributes', () => {
    mount(ChatWidget, {
      props: {
        siteId: 'test-uuid',
        botName: 'Test Agent',
        position: 'bottom-left',
        size: 100
      }
    });

    const script = document.querySelector('script[data-site-id="test-uuid"]');
    expect(script.getAttribute('data-bot-name')).toBe('Test Agent');
    expect(script.getAttribute('data-position')).toBe('bottom-left');
    expect(script.getAttribute('data-size')).toBe('100');
  });

  it('should cleanup script on unmount', () => {
    const wrapper = mount(ChatWidget, {
      props: { siteId: 'test-uuid' }
    });

    let script = document.querySelector('script[data-site-id="test-uuid"]');
    expect(script).toBeTruthy();

    wrapper.unmount();

    script = document.querySelector('script[data-site-id="test-uuid"]');
    expect(script).toBeFalsy();
  });
});

Troubleshooting

This happens if the component re-renders frequently. Move the widget to a higher-level component (like App.vue) that doesn't re-render often.

Dynamic variables not updating

The widget only reads data-dynamic-variables once on initialization. To update variables, you need to remount the component:

<template>
  <ChatWidget
    :key="widgetKey"
    site-id="YOUR_SITE_UUID"
    :dynamic-variables="dynamicVariables"
  />
</template>

<script setup>
import { ref } from 'vue';

const widgetKey = ref(0);
const dynamicVariables = ref({ user_name: 'John' });

const updateUserContext = (newVariables) => {
  dynamicVariables.value = newVariables;
  widgetKey.value++; // Force re-mount
};
</script>

If using Vite, ensure CSP headers allow the widget script. Check browser console for CSP errors.

Best Practices

Mount at app level: Place <ChatWidget> in App.vue to avoid re-mounting
Use composables: Extract widget logic into reusable composables
TypeScript: Use provided TypeScript types for better DX
Lazy load: Use Vue's defineAsyncComponent for code-splitting if widget isn't always needed
Error boundaries: Handle script loading errors gracefully
Clean up: Always call destroy() in onBeforeUnmount to properly remove the widget

Next Steps

React integration: See React Integration
Next.js integration: See Next.js Integration
Custom styling: Customize widget appearance - see Custom Styling
Page integration: Let the agent interact with your Vue app - see Page Integration
API reference: Learn about the Widget API - see Widget API

Need Help?

Documentation: Widget Integration Guide
Support: support@hiroi.ai
Dashboard: Manage your agents