Vanilla JavaScript, Vue, Svelte & More

This guide works with Vue, Svelte, Angular, or plain JavaScript — either via script tag or npm. Using React or Next.js? Try the React Quick Start or Next.js Quick Start instead.

Option 1: Script Tag (Recommended)

Add the Grain Tag script to your HTML:

<script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>

Replace your-tenant-id with your tenant identifier from your dashboard. Then get the SDK instance in your JavaScript:

const grain = GrainTag.getInstance();

Option 2: npm Package

Install via your package manager:

npm

npm install @grainql/tag

yarn

yarn add @grainql/tag

pnpm

pnpm add @grainql/tag

Then import and initialize:

import { init, track, identify, getInstance } from '@grainql/tag';

init({ tenantId: 'your-tenant-id' });

With the npm package, you can use the top-level exports (track, identify) directly, or get the instance with getInstance().

Automatic Tracking

Grain Tag automatically tracks the following with zero configuration:

Page views — including SPA navigation via the History API
Heatmap clicks — click positions with element identification
Scroll depth — how far users scroll on each page
DOM snapshots — visual page captures for heatmap overlays
Sessions — session start/end with duration
Device, browser, and OS — automatically detected
UTM parameters and referrer — captured on first visit

No manual page_viewed calls are needed. Grain Tag hooks into pushState and replaceState automatically.

Track Custom Events

Call track() with an event name and optional properties:

// Script tag approach
const grain = GrainTag.getInstance();
grain.track('button_clicked', {
  button_name: 'signup',
  location: 'hero'
});

// npm approach
import { track } from '@grainql/tag';
track('button_clicked', {
  button_name: 'signup',
  location: 'hero'
});

Events are automatically batched and sent. You don’t need to manually flush.

Identify Users

Associate events with a specific user:

// Script tag approach
const grain = GrainTag.getInstance();
grain.identify('user_123');

// npm approach
import { identify } from '@grainql/tag';
identify('user_123');

// All subsequent events include this user ID

Grain is cookieless by default with daily rotating IDs. When you need explicit consent handling:

const grain = GrainTag.getInstance();

// Grant consent (enables persistent tracking)
grain.consent.grant();

// Revoke consent
grain.consent.revoke();

// Check consent status
const status = grain.consent.status();

Complete Example

Here’s a small app that puts it all together:

<!DOCTYPE html>
<html lang="en">
<head>
  <script src="https://tag.grainql.com/v4/your-tenant-id.js"></script>
</head>
<body>
  <div id="hero">
    <h1>Welcome!</h1>
  </div>
  <button id="signup-btn">Get Started</button>

  <script>
    const grain = GrainTag.getInstance();

    // Track button clicks
    document.querySelector('#signup-btn').addEventListener('click', () => {
      grain.track('signup_clicked', { location: 'hero' });
    });

    // Identify user after login
    async function handleLogin(email, password) {
      const user = await loginUser(email, password);
      grain.identify(user.id);
    }
  </script>
</body>
</html>

Vue.js Example

Using Grain Tag in a Vue component: Script tag approach (add <script src="https://tag.grainql.com/v4/your-tenant-id.js"></script> to your index.html):

<template>
  <div>
    <h1>{{ title }}</h1>
    <button @click="handleClick">Get Started</button>
  </div>
</template>

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

const title = ref('Welcome!');

const handleClick = () => {
  const grain = GrainTag.getInstance();
  grain.track('button_clicked', { location: 'hero' });
};
</script>

npm approach:

<template>
  <div>
    <h1>{{ title }}</h1>
    <button @click="handleClick">Get Started</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { track } from '@grainql/tag';

const title = ref('Welcome!');

const handleClick = () => {
  track('button_clicked', { location: 'hero' });
};
</script>

Initialize Grain once in your app entry point (main.ts):

import { createApp } from 'vue';
import { init } from '@grainql/tag';
import App from './App.vue';

init({ tenantId: 'your-tenant-id' });

createApp(App).mount('#app');

Page views are tracked automatically — Grain Tag hooks into Vue Router’s History API navigation.

Svelte Example

Using Grain Tag in a Svelte component: Script tag approach (add <script src="https://tag.grainql.com/v4/your-tenant-id.js"></script> to your app.html):

<script>
  function handleClick() {
    const grain = GrainTag.getInstance();
    grain.track('button_clicked', { location: 'hero' });
  }
</script>

<div>
  <h1>Welcome!</h1>
  <button on:click={handleClick}>Get Started</button>
</div>

npm approach:

<script>
  import { track } from '@grainql/tag';

  function handleClick() {
    track('button_clicked', { location: 'hero' });
  }
</script>

<div>
  <h1>Welcome!</h1>
  <button on:click={handleClick}>Get Started</button>
</div>

Initialize Grain once in your app entry point:

// src/main.ts
import { init } from '@grainql/tag';
import App from './App.svelte';

init({ tenantId: 'your-tenant-id' });

const app = new App({ target: document.getElementById('app')! });
export default app;

Page views are tracked automatically — Grain Tag hooks into SvelteKit’s History API navigation.

What’s Next?

Core API Reference

See all available methods and options

User Identification

Learn about tracking users across sessions

Trackers

Track element clicks without writing code

Event Best Practices

Learn what to track and how to structure events

Need remote configuration or feature flags? See @grainql/analytics-web for remote config support, React hooks, and more.

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Vanilla JavaScript, Vue, Svelte & More

Option 1: Script Tag (Recommended)

Option 2: npm Package

Automatic Tracking

Track Custom Events

Identify Users

Complete Example

Vue.js Example

Svelte Example

What’s Next?

Core API Reference

User Identification

Trackers

Event Best Practices

​Option 1: Script Tag (Recommended)

​Option 2: npm Package

​Automatic Tracking

​Track Custom Events

​Identify Users

​Consent Management

​Complete Example

​Vue.js Example

​Svelte Example

​What’s Next?

Core API Reference

User Identification

Trackers

Event Best Practices

Option 1: Script Tag (Recommended)

Option 2: npm Package

Automatic Tracking

Track Custom Events

Identify Users

Consent Management

Complete Example

Vue.js Example

Svelte Example

What’s Next?