No results for ""
  • Home
  • API docs


Vue SDK reference

Read time: 6 minutes
Last edited: Mar 06, 2024
Version 2 of the Vue SDK replaces users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

Code samples on this page are from the two most recent SDK versions where they differ. To learn more about upgrading, read Vue SDK 1.x to 2.0 migration guide.


This topic documents how to get started with the Vue SDK.

SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

SDK API documentationSDK API docs
GitHub repositoryvue-client-sdk
Sample applicationVue
Published modulenpm
The Vue SDK is based on the JavaScript SDK

The Vue SDK builds on LaunchDarkly's JavaScript SDK to provide a better integration for use in Vue applications. As a result, much of the JavaScript SDK functionality is also available for the Vue SDK to use. For a complete client-side JavaScript SDK reference, read JavaScript SDK reference.

SDK version compatibility

The LaunchDarkly Vue SDK only works with Vue 3:

  • Vue SDK 2.0 requires Vue 3.2 or newer
  • Vue SDK 1.x requires Vue 3 or newer

For Vue 2 projects, you can use the JavaScript SDK directly, or a community-developed package such as vue-ld.

Getting started

After you complete the Getting started process, follow these instructions to start using the LaunchDarkly SDK in your Vue project.

Making feature flags available to this SDK

You must make feature flags available to client-side SDKs before the SDK can evaluate those flags. If an SDK tries to evaluate a feature flag that is not available, the end user will receive the fallback value for that flag.

To make a flag available to this SDK, check the SDKs using Client-side ID checkbox during flag creation, or on the flag's Settings tab. To make all of a project's flags available to this SDK by default, check the SDKs using Client-side ID checkbox in your project Settings.

The Vue SDK uses a client-side ID

The Vue SDK uses a client-side ID. Your environment's client-side ID is available in the Projects tab of your Account settings page. To learn more about key types, read Keys.

To install the Vue SDK, you need your LaunchDarkly environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

Never embed a server-side SDK key into a client-side application

Client-side IDs are not secret and you can expose them in your client-side code without risk. However, never embed a server-side SDK key into a client-side application.

Install the Vue SDK using either npm or yarn:

npm install --save launchdarkly-vue-client-sdk

After you install the dependency, add the LaunchDarkly plugin to your Vue app. Typically you do this in main.js:

import { createApp } from 'vue'
import App from './App.vue'
import { LDPlugin } from 'launchdarkly-vue-client-sdk'
const clientSideID = 'client-side-id-123abc'
const app = createApp(App)
app.use(LDPlugin, { clientSideID })

Configuring the Vue SDK

The SDK provides a Vue plugin that you can add to your app. You can pass configuration options to the plugin when it loads, or to the ldInit function if you are using the deferInitialization option. To learn more, read Initializing the client. To learn more about the available configuration options, read LDPluginOptions.

Using the plugin

The plugin exposes the LaunchDarkly client, as well as some convenience functions. As it uses the Vue provide/inject API to do this, these functions will only work when run within Vue's setup hook or <script setup>. To learn more, read Provide/Inject.

Initializing the LaunchDarkly client

The SDK automatically initializes the LaunchDarkly client if you provide a clientSideID, and do not use the deferInitialization option. Otherwise, you will need to initialize the LaunchDarkly client manually with ldInit, which accepts the same options as the plugin.

For example, if you do not know the context at plugin load time and need to defer initialization until you do, you can use the deferInitialization option.

In the App.vue using the v2 Vue SDK, you initialize a context. In the v1.x example, you initialize a user. Here's how:

import { createApp } from 'vue'
import App from './App.vue'
import { LDPlugin } from 'launchdarkly-vue-client-sdk'
const app = createApp(App)
app.use(LDPlugin, { clientSideID: 'client-side-id-123abc', deferInitialization: true })

To learn more, read the API documentation for ldInit.

Use ldReady to check when the LaunchDarkly client has finished initializing. This is returned by ldInit. You can also retrieve it independently with useLDReady. ldReady is a ref, so to access its value outside of a template you need to use ldReady.value.

Here's how:

<script setup lang="ts">
import { useLDReady } from 'launchdarkly-vue-client-sdk'
const ldReady = useLDReady()
<div v-if="ldReady">... content that uses LaunchDarkly ...</div>
<div v-else>LaunchDarkly client initializing...</div>

Retrieving flag values with the client

Use useLDFlag to access a single flag value by key. It returns a readonly ref for the value of a flag. If you are using TypeScript, the ref's type can be inferred from the type of the fallback value provided to useLDFlag. To learn more about Vue refs, read ref in the Vue.js documentation.

Example usage:

<script setup lang="ts">
import { useLDFlag } from 'launchdarkly-vue-client-sdk'
const featureFlagKey = 'my-boolean-flag'
const myFlagValue = useLDFlag(featureFlagKey, false /* default flag value */)
Feature flag "{{ featureFlagKey }}" has value "{{ myFlagValue }}".

The Vue SDK automatically subscribes to flag change events with useLDFlag, which opens a streaming connection. Then, your component re-renders automatically when flag changes occur.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. If you do not want flag updates streamed to your application, you can disable this by including the streaming: false option when you load the plugin or when you call ldInit.

In other cases, streaming may be required. If you call useLDFlag, the SDK automatically opens a streaming connection. This is a benefit of useLDFlag as compared with getting flag values using the underlying JavaScript SDK, for example with ldClient.variant() or ldClient.allFlags().

To learn more, read useLDFlag.

You may also access the LaunchDarkly client with useLDClient, the LDClient object from the underlying JavaScript SDK.

Here is an example:

<script setup>
import { useLDClient } from 'launchdarkly-vue-client-sdk'
const [ldReady] = ldInit({ clientSideID, context })
const ldClient = useLDClient()
<div v-if="ldReady">
<p>All flags: {{ JSON.stringify(ldClient.allFlags()) }}</p>
<div v-else>LaunchDarkly client initializing...</div>

Example app

An example app is included in launchdarkly/vue-client-sdk.

To run it, use:

git clone
cd vue-client-sdk
npm i
npm start