> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Vue

> Use schematic-vue to quickly identify users, track events, and check flags client-side in your vue app with Schematic.

`schematic-vue` is a client-side Vue library for [Schematic](https://schematichq.com) which provides composables to track events, check flags, and more. `schematic-vue` provides the same capabilities as [schematic-js](https://github.com/schematichq/schematic-js/tree/main/js), for Vue apps.

## Install

```bash
npm install @schematichq/schematic-vue
# or
yarn add @schematichq/schematic-vue
# or
pnpm add @schematichq/schematic-vue
```

## Usage

### SchematicPlugin

You can use the `SchematicPlugin` to make Schematic available throughout your Vue application:

```typescript
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";
import App from "./App.vue";

const app = createApp(App);
app.use(SchematicPlugin, { publishableKey: "your-publishable-key" });
app.mount("#app");
```

### Setting context

To set the user context for events and flag checks, you can use the `identify` function provided by the `useSchematicEvents` composable:

```vue
<script setup lang="ts">
import { onMounted } from "vue";
import { useSchematicEvents } from "@schematichq/schematic-vue";

const { identify } = useSchematicEvents();

onMounted(() => {
  identify({
    keys: { id: "my-user-id" },
    company: {
      keys: { id: "my-company-id" },
      traits: { location: "Atlanta, GA" },
    },
  });
});
</script>
```

To learn more about identifying companies with the `keys` map, see [key management in Schematic public docs](/developer_resources/key_management).

### Tracking usage

Once you've set the context with `identify`, you can track events:

```vue
<script setup lang="ts">
import { useSchematicEvents } from "@schematichq/schematic-vue";

const { track } = useSchematicEvents();

function handleQuery() {
  track({ event: "query" });
}
</script>

<template>
  <button @click="handleQuery">Run Query</button>
</template>
```

If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:

```typescript
track({ event: "query", quantity: 10 });
```

### Checking flags

To check a flag, you can use the `useSchematicFlag` composable:

```vue
<script setup lang="ts">
import { useSchematicFlag } from "@schematichq/schematic-vue";

const isFeatureEnabled = useSchematicFlag("my-flag-key");
</script>

<template>
  <div v-if="isFeatureEnabled">
    <Feature />
  </div>
  <div v-else>
    <Fallback />
  </div>
</template>
```

### Checking entitlements

You can check entitlements (i.e., company access to a feature) using a flag check as well, and using the `useSchematicEntitlement` composable you can get additional data to render various feature states:

```vue
<script setup lang="ts">
import {
  useSchematicEntitlement,
  useSchematicIsPending,
} from "@schematichq/schematic-vue";

const schematicIsPending = useSchematicIsPending();
const {
  featureAllocation,
  featureUsage,
  featureUsageExceeded,
  value: isFeatureEnabled,
} = useSchematicEntitlement("my-flag-key");
</script>

<template>
  <!-- Loading state -->
  <Loader v-if="schematicIsPending" />

  <!-- Usage exceeded state -->
  <div v-else-if="featureUsageExceeded">
    You have used all of your usage ({{ featureUsage }} / {{ featureAllocation }})
  </div>

  <!-- Either feature state or "no access" state -->
  <Feature v-else-if="isFeatureEnabled" />
  <NoAccess v-else />
</template>
```

*Note: `useSchematicIsPending` is checking if entitlement data has been loaded, typically via `identify`. It should, therefore, be used to wrap flag and entitlement checks, but never the initial call to `identify`.*

### Usage warnings

If a [usage warning](/feature-management/usage-warnings) is configured on the entitlement, the composable also exposes `warningTiers`, so you can warn a customer before they hit a limit rather than after. Each tier is a `{ key, value }` pair in the entitlement's usage units, and the dashboard writes a single tier under the key `default`:

```vue
<script setup lang="ts">
import { computed } from "vue";
import { useSchematicEntitlement } from "@schematichq/schematic-vue";

const { featureUsage, warningTiers } = useSchematicEntitlement("my-flag-key");

const warning = computed(() =>
  warningTiers.value?.find((tier) => tier.key === "default"),
);
const approachingLimit = computed(
  () =>
    typeof featureUsage.value === "number" &&
    typeof warning.value?.value === "number" &&
    featureUsage.value >= warning.value.value,
);
</script>
```

### Company plan information

To access the current company's plan and trial status, you can use the `useSchematicPlan` composable:

```vue
<script setup lang="ts">
import { useSchematicPlan } from "@schematichq/schematic-vue";

const plan = useSchematicPlan();
</script>

<template>
  <div v-if="!plan">No plan assigned</div>
  <div v-else>
    <p>Current plan: {{ plan.name }}</p>

    <p v-if="plan.trialStatus === 'active'">
      Trial ends: {{ plan.trialEndDate?.toLocaleDateString() }}
    </p>

    <p v-if="plan.trialStatus === 'expired'">
      Your trial has ended. <a href="/upgrade">Upgrade now</a>
    </p>
  </div>
</template>
```

The composable returns an object with the following properties:

| Property       | Type                                                | Description                                                                                                                                                                                                         |
| -------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string`                                            | The plan ID                                                                                                                                                                                                         |
| `name`         | `string`                                            | The plan name                                                                                                                                                                                                       |
| `trialEndDate` | `Date \| undefined`                                 | The trial end date, if the company has or had a trial                                                                                                                                                               |
| `trialStatus`  | `"active" \| "expired" \| "converted" \| undefined` | The company's trial status: `active` if the trial is ongoing, `expired` if the trial ended without conversion, `converted` if the company converted to a paid plan, or `undefined` if the company has never trialed |

### Credit balances

To display a company's credit balance, use the `useSchematicCreditBalance` composable. It is keyed by credit ID and updates reactively as the balance changes over the DataStream, so the number stays accurate while leases open and close:

```vue
<script setup lang="ts">
import { useSchematicCreditBalance } from "@schematichq/schematic-vue";

const { balance, isLoading } = useSchematicCreditBalance("credit-id");
</script>

<template>
  <div v-if="isLoading">Loading…</div>
  <div v-else>{{ balance }} credits remaining</div>
</template>
```

The composable returns an object with the following reactive properties:

| Property    | Type                   | Description                                                                                     |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------- |
| `balance`   | `ComputedRef<number>`  | The spendable balance, or `0` while loading or when the company holds no balance in this credit |
| `isLoading` | `ComputedRef<boolean>` | `true` while the balance is still loading and no value has arrived yet                          |

The composable surfaces the `settled` balance, which is the spendable number you should show end users. For advanced lease-aware accounting, read the underlying client instead: `client.getCreditBalance(creditId)` returns all three views of the balance: `settled`, `remaining` (excluding open lease holds), and `reserved` (the amount held by open leases):

```ts
import { useSchematicClient } from "@schematichq/schematic-vue";

const client = useSchematicClient();
const balance = client.getCreditBalance("credit-id"); // { settled, remaining, reserved } | undefined
```

`getCreditBalance` returns a point-in-time snapshot; to react to changes, subscribe with `client.addCreditBalanceListener(callback)`.

The credit ID is available on a feature's entitlement: `useSchematicEntitlement(key)` returns `creditId` for credit-based features.

*Note: `useSchematicCreditBalance` requires `@schematichq/schematic-vue` 1.5.0 or later.*

## Fallback Behavior

The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

### Flag Check Fallbacks

When flag checks cannot reach Schematic, they use fallback values in the following priority order:

1. Callsite fallback - fallback values can be provided directly in the composable options
2. Initialization defaults - fallback values configured via `flagCheckDefaults` or `flagValueDefaults` options when initializing the plugin
3. Default value - Returns `false` if no fallback is configured

```vue
<script setup lang="ts">
// Provide a fallback value at the callsite
import { useSchematicFlag } from "@schematichq/schematic-vue";

const isFeatureEnabled = useSchematicFlag("feature-flag", {
    fallback: true,  // Used if API request fails
});
</script>

<template>
    <Feature v-if="isFeatureEnabled" />
    <Fallback v-else />
</template>
```

```typescript
// Or configure defaults at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
    publishableKey: "your-publishable-key",
    flagValueDefaults: {
        "feature-flag": true,  // Used if API request fails and no callsite fallback
    },
    flagCheckDefaults: {
        "another-flag": {
            flag: "another-flag",
            value: true,
            reason: "Default value",
        },
    },
});
```

### Event Queueing and Retry

When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:

* Events are queued in memory (up to 100 events by default, configurable via `maxEventQueueSize`)
* Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via `maxEventRetries`)
* Events are automatically flushed when the network connection is restored
* Events queued when the page is hidden are sent when the page becomes visible

### WebSocket Fallback

In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as [outlined above](#flag-check-fallbacks). The WebSocket will also automatically attempt to re-establish its connection with Schematic using an exponential backoff.

## Options API Support

While the primary API uses the Composition API, you can still use these composables in the Options API:

```vue
<script>
import { useSchematicFlag, useSchematicEvents } from "@schematichq/schematic-vue";

export default {
  setup() {
    const isFeatureEnabled = useSchematicFlag("my-flag-key");
    const { track } = useSchematicEvents();

    return {
      isFeatureEnabled,
      track,
    };
  },
  methods: {
    handleAction() {
      this.track({ event: "action" });
    },
  },
};
</script>
```

## Troubleshooting

For debugging and development, Schematic supports two special modes:

### Debug Mode

Enables console logging of all Schematic operations:

```typescript
// Enable at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
  publishableKey: "your-publishable-key",
  debug: true,
});

// Or via URL parameter
// https://yoursite.com/?schematic_debug=true
```

### Offline Mode

Prevents network requests and returns fallback values for all flag checks:

```typescript
// Enable at initialization
import { createApp } from "vue";
import { SchematicPlugin } from "@schematichq/schematic-vue";

const app = createApp(App);
app.use(SchematicPlugin, {
  publishableKey: "your-publishable-key",
  offline: true,
});

// Or via URL parameter
// https://yoursite.com/?schematic_offline=true
```

Offline mode automatically enables debug mode to help with troubleshooting.

## Advanced Usage

### Using a Pre-configured Client

If you need more control over the Schematic client initialization, you can create a client instance and pass it to the plugin:

```typescript
import { createApp } from "vue";
import { Schematic } from "@schematichq/schematic-js";
import { SchematicPlugin } from "@schematichq/schematic-vue";
import App from "./App.vue";

const client = new Schematic("your-publishable-key", {
  useWebSocket: true,
  debug: true,
});

const app = createApp(App);
app.use(SchematicPlugin, { client });
app.mount("#app");
```

### Per-Component Client Override

You can override the client for a specific component by passing a `client` option to any composable:

```typescript
import { useSchematicFlag } from "@schematichq/schematic-vue";
import { Schematic } from "@schematichq/schematic-js";

const customClient = new Schematic("different-api-key");
const isFeatureEnabled = useSchematicFlag("my-flag-key", {
  client: customClient,
});
```

## Server-Side Rendering (SSR)

All composables are SSR-compatible and work seamlessly with Nuxt and other Vue SSR frameworks:

* Initial flag/entitlement values are retrieved synchronously for server-side rendering
* Real-time subscriptions are deferred to client-side hydration
* No special configuration needed - it just works!

```typescript
// plugins/schematic.ts
import { SchematicPlugin } from '@schematichq/schematic-vue'

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  nuxtApp.vueApp.use(SchematicPlugin, { publishableKey: config.public.schematicPublishableKey })
})
```

```vue
<!-- Works in Nuxt/SSR -->
<script setup lang="ts">
import { useSchematicFlag } from "@schematichq/schematic-vue";

// Initial value available on server, updates subscribed on client
const isFeatureEnabled = useSchematicFlag("my-feature");
</script>
```

## License

MIT

## Support

Need help? Please open a GitHub issue or reach out to [support@schematichq.com](mailto:support@schematichq.com) and we'll be happy to assist.

> Use schematic-vue to quickly identify users, track events, and check flags client-side in your vue app with Schematic.