@quiltt/vue

Vue 3 composables and components for Quiltt Connector.

For general project information and contributing guidelines, see the main repository README.

Installation

npm install @quiltt/vue vue

Core Modules and Types

@quiltt/vue re-exports all functionality from @quiltt/core, so you only need to install this one package to access core API clients, authentication utilities, storage, and TypeScript types along with Vue components and composables. See the Core README for more information.

Quick Start

// main.ts
import { createApp } from 'vue'
import { QuilttPlugin } from '@quiltt/vue'

createApp(App).use(QuilttPlugin).mount('#app')

<script setup lang="ts">
import { QuilttButton, useQuilttSession } from '@quiltt/vue'

const { importSession } = useQuilttSession()

// Set session token when available (e.g., after login)
const onLogin = async (token: string) => {
  await importSession(token)
}
</script>

<template>
  <QuilttButton
    connector-id="YOUR_CONNECTOR_ID"
    @exit-success="(m) => console.log('Connected:', m.connectionId)"
  >
    Add Bank Account
  </QuilttButton>
</template>

Components

For better tree-shaking, you can import components from subpaths:

import { QuilttButton } from '@quiltt/vue/components'

QuilttButton

Opens the connector in a modal overlay. Supports custom click handlers via @click event.

<QuilttButton 
  connector-id="YOUR_CONNECTOR_ID" 
  @click="handleClick"
  @exit-success="handleSuccess"
>
  Connect Account
</QuilttButton>

To prevent the connector from opening, call event.preventDefault() in your click handler:

const handleClick = (event: MouseEvent) => {
  // Perform validation
  if (!isReady) {
    event.preventDefault() // Prevents connector from opening
  }
}

QuilttContainer

Renders the connector inline.

<QuilttContainer connector-id="YOUR_CONNECTOR_ID" theme-mode="auto" @exit-success="handleSuccess" />

Composables

For better tree-shaking, you can import composables from subpaths:

import { useQuilttSession } from '@quiltt/vue/composables'

useQuilttSession

import { useQuilttSession } from '@quiltt/vue'

const {
  session,             // Reactive session state
  importSession,       // Import an existing token
  identifySession,     // Start auth flow (email/phone)
  authenticateSession, // Complete auth (passcode)
  revokeSession,       // Invalidate session server-side
  forgetSession,       // Clear session locally
} = useQuilttSession('YOUR_ENVIRONMENT_ID') // environmentId is optional

await importSession('YOUR_SESSION_TOKEN')
console.log(session.value?.token)

Pass environmentId to restrict session import to a specific Quiltt environment (e.g. env_sandbox_... vs env_live_...). If provided, importSession will reject tokens whose JWT claims don't match.

useQuilttConnector

import { useQuilttConnector } from '@quiltt/vue'

const { open } = useQuilttConnector('YOUR_CONNECTOR_ID', {
  onExitSuccess: (m) => console.log('Connected:', m.connectionId),
  themeMode: 'auto',
})

<button @click="open">Add Account</button>

Best Practice: Memoize callback functions to avoid warnings and prevent unexpected behavior:

import { computed } from 'vue'

const handleExitSuccess = computed(() => (m) => {
  console.log('Connected:', m.connectionId)
})

const { open } = useQuilttConnector('YOUR_CONNECTOR_ID', {
  onExitSuccess: handleExitSuccess.value,
})

Additional Composables

@quiltt/vue also exports:

• useQuilttInstitutions — Search available institutions for a connector.
• useQuilttResolvable — Check if a provider connection can be resolved.
• useQuilttSettings — Access plugin-provided settings such as clientId.
• useSession — Low-level reactive session state manager.
• useStorage — Reactive wrapper around Quiltt global storage.

Composable context behavior:

• useQuilttSession, useQuilttInstitutions, and useQuilttResolvable require QuilttPlugin provider context and throw if used without it.
• useQuilttConnector continues without plugin session context and logs a warning.
• useQuilttSettings returns undefined values when plugin context is unavailable.

Plugin Exports

You can import plugin utilities from the dedicated subpath:

import { QuilttPlugin, QuilttSessionKey, QuilttSetSessionKey } from '@quiltt/vue/plugin'

Props and Events

| Prop | Type | Default | Description | | ------ | ------ | ------ | ------------- | | connector-id | string | — | Required. Quiltt Connector ID | | connection-id | string | — | Existing connection ID for reconnection | | institution | string | — | Pre-select an institution | | theme-mode | 'light' \| 'dark' \| 'auto' | — | Connector UI theme mode | | app-launcher-url | string | — | Deep link URL for OAuth callbacks | | force-remount-on-connection-change | boolean | false | Force complete remount when connectionId changes (useful as fallback for clean state) |

| Event | Payload | Description | | ------- | --------- | ------------- | | @load | metadata | Connector loaded | | @open | metadata | Connector opened (modal/inline) | | @exit | type, metadata | Connector exited (any reason) | | @exit-success | metadata | Connection successful | | @exit-abort | metadata | User cancelled | | @exit-error | metadata | Error occurred | | @event | type, metadata | Any connector event |

Reconnection

Pass connection-id to reconnect an existing connection:

<QuilttButton connection-id="YOUR_EXISTING_CONNECTION_ID" ... />

When connection-id changes, the component automatically updates the existing connector instance with the new connection details. To force a complete remount instead, use force-remount-on-connection-change:

<QuilttButton 
  connection-id="YOUR_EXISTING_CONNECTION_ID"
  force-remount-on-connection-change
  ...
/>

Capacitor / Ionic

For mobile apps, use @quiltt/capacitor/vue which adds native OAuth handling:

import { QuilttConnector, QuilttConnectorPlugin } from '@quiltt/capacitor/vue'

// Handle OAuth deep links
QuilttConnectorPlugin.addListener('deepLink', ({ url }) => {
  connectorRef.value?.handleOAuthCallback(url)
})

See @quiltt/capacitor for full documentation.

Resources

• Vue SDK Guide
• Issuing Session Tokens
• Connector Configuration

License

This project is licensed under the terms of the MIT license. See the LICENSE file for more information.

Contributing

For information on how to contribute to this project, please refer to the repository contributing guidelines.

Related Packages

• @quiltt/core - Essential functionality and types
• @quiltt/react - React components and hooks
• @quiltt/react-native - React Native and Expo components
• @quiltt/capacitor - Capacitor plugin and mobile framework adapters