Skip to main content
Courier Vue Inbox The Courier Vue SDK provides ready-made components and a programmatic composable for building notification experiences:
  • <CourierInbox /> — full-featured inbox for displaying and managing messages
  • <CourierInboxPopupMenu /> — popup menu version of the inbox
  • <CourierToast /> — toast notifications for time-sensitive alerts
  • <CourierPreferences /> — notification preferences center for managing topic subscriptions and delivery
  • useCourier() — composable for programmatic access and custom UIs
See these components in action with the interactive Inbox demo — no setup required.

Installation

Available on GitHub and npm.
vue (>= 3.3) is a peer dependency.
Not using Vue? Check out the @trycourier/courier-ui-inbox and @trycourier/courier-ui-toast packages instead, which provide Web Components for any JavaScript project.

Authentication

To use the SDK, you need to generate a JWT (JSON Web Token) for your user. This JWT should always be generated by your backend server, never in client-side code.
1

Your client calls your backend

When your app needs to authenticate a user, your client should make a request to your own backend (ex. GET https://your-awesome-app.com/api/generate-courier-jwt).
2

Your backend calls Courier

In your backend endpoint, use your Courier API Key to call the Courier Issue Token Endpoint and generate a JWT for the user.
3

Your backend returns the JWT to your client

Having received the JWT from Courier, your backend should return it to your client and pass it to the Courier SDK.
For a step-by-step walkthrough of authentication and token generation, see our JWT authentication tutorial.

Development testing with cURL

To quickly test JWT generation for development only, you can call the Issue Token Endpoint directly.
Do not call the Issue Token API from client-side code. Always keep your Courier API keys secure.

Quick Start

Get up and running with Courier Vue in minutes. This minimal example shows how to add the inbox component to your app. Courier components are normal Vue components — import them and use them in your template.
Follow the inbox implementation tutorial for detailed step-by-step guidance including backend JWT generation.

Inbox Component

<CourierInbox />

If you’re using tenants, scope requests to a particular tenant by passing its ID to signIn:
For the full reference of sign in parameters, see the Courier JS docs.

<CourierInboxPopupMenu />

Tabs and Feeds

Tabs and feeds organize and filter messages in the inbox. A feed is a container that groups related tabs together. Each tab applies filters to show relevant messages. Pass them with the :feeds prop.
If there is only one feed, the feed selection dropdown is hidden. If a feed has only one tab, the tab bar is hidden and the unread count appears next to the feed.
Filter options for each tab:

Handle Clicks and Presses

Listen for interactions with @message-click, @message-action-click, and @message-long-press.
message-long-press is only applicable on devices that support touch events.

Styles and Theming

Customize the inbox to match your app with a theme object passed to :light-theme and/or :dark-theme. Pass the object directly — the component serializes it for you.
Theme utilities: defaultLightTheme / defaultDarkTheme provide the default inbox themes, and mergeTheme(baseTheme, overrideTheme) merges two themes with the override taking precedence. The full CourierInboxTheme type covers the popup trigger button, the inbox window (header, feeds, tabs, actions), the message list (items, scrollbar, menus), and loading/empty/error states. Every property is optional. See the complete reference in the Courier React SDK theme reference (the theme object is identical across SDKs).

Fixed height

<CourierInbox /> has a default height of auto. Set a fixed height with the height prop:

Custom Elements

You can customize individual parts of the inbox by passing render props — functions that receive typed props and return a Vue node built with h(). Bind them with :render-*. You can also reach the underlying web component for imperative methods (e.g. removeHeader()) via a template ref — the component exposes getElement():

Toast Component

<CourierToast />

Toasts are short-lived notifications that notify users and prompt them to take action. The Toast component is connected to the feed of Courier Inbox messages.
Some initialization for toasts is asynchronous. If your app displays toasts immediately when the component is mounted, use the @ready event to wait until the component is fully initialized.

Handle Clicks

Styles and Theming

Toast theme utilities: defaultToastLightTheme / defaultToastDarkTheme for defaults, and mergeToastTheme(baseTheme, overrideTheme) to merge.

Custom Elements

CourierToast Props

Preferences Component

<CourierPreferences />

The Preferences component lets your users manage which topics they’re subscribed to and how each topic is delivered (per-channel routing and digest schedules), directly inside your Vue app.
Authentication requires a JWT that includes the read:preferences and write:preferences scopes.

CourierPreferences Props

Preferences theme utilities: defaultPreferencesLightTheme / defaultPreferencesDarkTheme for defaults, and mergePreferencesTheme(mode, overrideTheme) to merge.

useCourier Composable

The useCourier() composable provides programmatic access to Courier functionality for building 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>, and they auto-unwrap in templates.

When to use the composable vs components

  • Components (<CourierInbox />, <CourierToast />): quick integration with default UI
  • Composable (useCourier()): custom UIs, programmatic control, advanced state management
  • Both together: use the composable for state management while components handle rendering

Composable return value

You must call inbox.value.listenForUpdates() after authentication to enable real-time message updates. Without this, the inbox only shows messages from the initial load.
Complete example — authentication, inbox setup, real-time updates, and displaying messages. Note templates auto-unwrap the refs (inbox.totalUnreadCount, inbox.feeds[...]):

Inbox methods

Advanced

EU and regional endpoints

Only needed if your workspace uses the EU datacenter. @trycourier/courier-vue re-exports EU_COURIER_API_URLS and getCourierApiUrlsForRegion from @trycourier/courier-js.

Server-side rendering

Courier Inbox and Toast render client-side only. They mount in onMounted (which never runs during SSR), so they work with Nuxt and other SSR setups without extra configuration — the components simply render once on the client.

Troubleshooting

Make sure you’ve called inbox.value.listenForUpdates() after authentication. This establishes the WebSocket connection required for real-time updates.
Possible causes:
  1. Not authenticated — ensure signIn() has been called
  2. Feeds not registered — call registerFeeds() before load()
  3. Network errors — check inbox.value.error for details
  4. JWT expired — generate a new token
  • Invalid JWT: Ensure the JWT is generated correctly on your backend
  • Expired JWT: JWTs have an expiration time; generate a new one
  • Missing scopes: Ensure your JWT includes inbox:read:messages and inbox:write:events
  • Wrong user ID: Verify the userId matches the user the JWT was issued for
Custom render props must return a Vue node built with h() (imported from vue), not a raw string of markup. Ensure the render prop is bound with :render-list-item="..." (kebab-case) on the component.
Import types directly from the package:

Best Practices

  • JWT Security: Always generate JWTs server-side. Cache on the client, refresh before expiration (standard: '1d'), include only necessary scopes.
  • Performance: Use canUseCache: true (default) for cached data. Set appropriate setPaginationLimit() values. The composable’s shallowRefs update automatically; avoid triggering unnecessary re-renders.
  • Testing: Mock useCourier() in tests to return test data:

TypeScript Types