Courier Vue SDK

The Vue SDK wraps Courier’s in-app components as Vue components, plus one composable that exposes the client behind them.

<CourierInbox />: inbox for displaying and managing messages
<CourierInboxPopupMenu />: popup menu version of the inbox
<CourierToast />: toast notifications for time-sensitive alerts
<CourierPreferences />: preference center for topic subscriptions and delivery
useCourier(): composable for custom UIs

See these components in the interactive Inbox demo. No setup required.

Installation

Available on GitHub and npm.

npm install @trycourier/courier-vue

vue (>= 3.3) is a peer dependency.

Not using Vue? Use the instead. Its elements work in any JavaScript project.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See .

const courier = useCourier();

courier.auth.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
courier.auth.signOut();
courier.auth.userId;                   // undefined when signed out

Quick start

Add the inbox component to your app. Courier components are normal Vue components. Import them and use them in your template.

<script setup lang="ts">
import { onMounted } from "vue";
import { CourierInbox, useCourier } from "@trycourier/courier-vue";

const courier = useCourier();

onMounted(() => {
  // Generate a JWT for your user on your backend server
  const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

  // Authenticate the user
  courier.shared.signIn({
    userId: "user_123",
    jwt: jwt,
  });
});
</script>

<template>
  <CourierInbox />
</template>

Follow the for step-by-step guidance, including backend JWT generation.

Component reference

Each component’s props, theme, callbacks, and custom-render surface live with the feature. These links open on the Vue tab.

To do this	Go here
Embed the inbox, or render it as a popup
Theme it, handle clicks, replace parts of it
Split it into filtered tabs and feeds
Add toasts, and set auto-dismiss
Theme a toast or replace it
Add a preference center
Theme preferences, or build your own
Send a message that reaches the inbox

Bind a render prop in kebab-case. Vue lowercases attribute names, so :render-list-item reaches the component and :renderListItem doesn’t. A custom render must also return a Vue node built with h(), not a string of markup. A string renders nothing. The CourierInboxTheme, CourierToastTheme, and CourierPreferencesTheme objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: , , .

useCourier composable

The useCourier() composable gives you programmatic access to Courier. Use it to build custom UIs. It returns the same shape as the React hook, but auth, inbox, and toast are Vue shallowRefs. Access them with .value in <script setup>. They auto-unwrap in templates.

When to use the composable vs components

Components (<CourierInbox />, <CourierToast />): quick integration with the default UI
Composable (useCourier()): custom UIs, programmatic control, state management
Both together: the composable manages state, components render

Composable return value

const { shared, auth, inbox, toast, preferences } = useCourier();

// In <script setup>, reactive slices need .value:
auth.value.signIn({ userId, jwt });
inbox.value.registerFeeds(defaultFeeds());
await inbox.value.listenForUpdates();
await inbox.value.load();
console.log(inbox.value.totalUnreadCount);

// `shared` and `preferences` are plain (no .value):
const prefs = await preferences.getUserPreferences();

Call inbox.value.listenForUpdates() after authentication to open the realtime connection. Without it, the inbox loads once from the initial fetch and doesn’t update again. Complete example: authentication, inbox setup, real-time updates, and displaying messages. Templates auto-unwrap the refs (inbox.totalUnreadCount, inbox.feeds[...]):

<script setup lang="ts">
import { onMounted } from "vue";
import { useCourier, defaultFeeds } from "@trycourier/courier-vue";

const { auth, inbox } = useCourier();

onMounted(async () => {
  auth.value.signIn({
    userId: "user_123",
    jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  });
  inbox.value.registerFeeds(defaultFeeds());
  await inbox.value.listenForUpdates();
  await inbox.value.load();
});
</script>

<template>
  <div>
    <div>Total Unread: {{ inbox.totalUnreadCount ?? 0 }}</div>
    <ul>
      <li
        v-for="message in inbox.feeds['all_messages']?.messages ?? []"
        :key="message.messageId"
        :style="{ backgroundColor: message.read ? 'transparent' : '#fee2e2', padding: '8px', marginBottom: '4px' }"
      >
        {{ message.title }}
      </li>
    </ul>
  </div>
</template>

Every method and reactive value the inbox slice exposes is in . Read them off inbox.value in <script setup>, and off inbox in a template.

Advanced

Server-side rendering

Courier Inbox and Toast render client-side only. They mount in onMounted, which never runs during SSR. They work with Nuxt and other SSR setups without extra configuration, rendering once on the client.

Troubleshooting

Inbox not updating in real-time

Call inbox.value.listenForUpdates() after authentication. It opens the WebSocket connection required for real-time updates.

auth.value.signIn({ userId, jwt });
inbox.value.registerFeeds(defaultFeeds());
await inbox.value.listenForUpdates(); // Required for real-time
await inbox.value.load();

Messages not loading

Possible causes:

Not authenticated: call signIn()
Feeds not registered: call registerFeeds() before load()
Network errors: check inbox.value.error for details
JWT expired: generate a new token

Authentication errors

Invalid JWT: generate the JWT correctly on your backend
Expired JWT: JWTs expire. Generate a new one
Missing scopes: include inbox:read:messages and inbox:write:events in the JWT
Wrong user ID: the userId must match the user the JWT was issued for

Custom slots not rendering

Custom render props must return a Vue node built with h() (imported from vue), not a raw string of markup. Bind the render prop with :render-list-item="..." (kebab-case) on the component.

TypeScript errors

Import types directly from the package:

import { useCourier, type InboxMessage, type CourierInboxFeed } from "@trycourier/courier-vue";

Best practices

JWT security: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: '1d'), and include only the scopes you need.
Performance: canUseCache: true (default) serves cached data. Set a suitable setPaginationLimit(). The composable’s shallowRefs update on their own, so avoid unnecessary re-renders.
Testing: mock useCourier() in tests to return test data:

import { ref } from "vue";

vi.mock("@trycourier/courier-vue", () => ({
  useCourier: () => ({
    inbox: ref({ feeds: { all_messages: { messages: mockMessages } }, totalUnreadCount: 5 }),
  }),
}));

TypeScript types

Show type InboxMessage

type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}

Show type InboxDataSet

type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}

Show type CourierInboxFeed

type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}

Show type CourierInboxTab

type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}

Show type CourierInboxDatasetFilter

type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
}

All filter properties are AND’d together. { tags: ['important'], status: 'unread' } shows unread messages tagged ‘important’.

Show type CourierToastItemFactoryProps

type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}

Get started

Server

Client

Courier Vue SDK

Installation

Authentication

Quick start

Component reference

useCourier composable

When to use the composable vs components

Composable return value

Advanced

Server-side rendering

Troubleshooting

Best practices

TypeScript types

​Installation

​Authentication

​Quick start

​Component reference

​useCourier composable

​When to use the composable vs components

​Composable return value

​Advanced

​Server-side rendering

​Troubleshooting

​Best practices

​TypeScript types

Installation

Authentication

Quick start

Component reference

useCourier composable

When to use the composable vs components

Composable return value

Advanced

Server-side rendering

Troubleshooting

Best practices

TypeScript types