@wetransform/vue

@wetransform/vue

Vue 3 wrapper around @wetransform/core with a composable API and a component.

SDK Guide — overview of the SDK packages and how to integrate them into your website

Installation

npm install @wetransform/vue

Component usage

<script setup lang="ts">
import { ref } from 'vue'
import { WeTransformSdk } from '@wetransform/vue'
import type { WeTransformConfig, WeTransformSdkProps, SupportedLocales } from '@wetransform/vue'

const isSdkOpen = ref(false)
const locale = ref<SupportedLocales>('en')

const config: WeTransformConfig = {
  organizationHandle: 'your_organization_handle',
  authentication: {
    customerId: 'your_customer_id',
    signature: 'your_signed_token',
  },
  // Optional theming (colors, font, border radius, dark mode). See @wetransform/core docs.
  customization: {
    colors: {
      primary: '#7c3aed',
      secondary: '#22d3ee',
      background: '#faf5ff',
    },
    font: {
      family: "'Inter', sans-serif",
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&display=swap',
    },
    borderRadius: {
      button: '8px',
      base: '8px',
    },
  },
}

const onSuccessSubmit: WeTransformSdkProps['onSuccessSubmit'] = ({
  customerId,
  templateHandle,
  fileUrl,
  signature,
}) => {
  // Handle post-submit
}
</script>

<template>
  <button type="button" @click="isSdkOpen = true">Open Sender</button>
  <button type="button" @click="locale = locale === 'en' ? 'fr' : 'en'">Toggle locale</button>

  <WeTransformSdk
    :config="config"
    v-model:open="isSdkOpen"
    :locale="locale"
    @successSubmit="onSuccessSubmit"
  />
</template>

WeTransformSdk is renderless except for its internal mount container and does not expose slots.

Props:

• config (required): SDK configuration (excludes locale; use the locale prop instead)
• open (optional): controlled open state (for v-model:open)
• autoOpen (optional, default false): opens on mount
• locale (optional): active locale ('en' | 'fr'); reactive — changing this prop calls setLocale on the SDK

Emits:

• update:open → (value: boolean)
• open
• close
• destroy
• ready
• successSubmit → (payload: { customerId: string; templateHandle: string; fileUrl: string; signature: string; userFileName: string })
• error → (payload: { code: string; message: string; stack?: string })

Composable usage

import { useWeTransform } from '@wetransform/vue'

const { open, close, destroy, setLocale, isOpen, weTransformInstance, on } = useWeTransform({
  organizationHandle: 'acme',
  authentication: {
    customerId: 'customer-id',
    signature: 'signed-token',
  },
})

on('successSubmit', ({ customerId, templateHandle, fileUrl, signature, userFileName }) => {
  // Handle post-submit
})

await open()
await setLocale('fr')
await close()
await destroy()

console.log(isOpen.value)
console.log(weTransformInstance.value)

useWeTransform(config) accepts a plain config object, a Ref<WeTransformConfig>, or a getter () => WeTransformConfig.

useWeTransform(config) returns:

• weTransformInstance: readonly Ref<WeTransformInstance | null>
• isOpen: readonly Ref<boolean>
• open(): opens the SDK
• close(): closes the SDK
• destroy(): destroys the SDK instance (idempotent)
• setLocale(locale): switches the locale ('en' | 'fr')
• on(event, handler): subscribes to SDK events and returns an unsubscribe function

Exports

@wetransform/vue also exports:

• WeTransformSdkProps — props type for the WeTransformSdk component

And re-exports these symbols from @wetransform/core:

• createWeTransform
• WeTransformConfig
• WeTransformEventMap
• WeTransformInstance
• WeTransformInitialLocations
• WeTransformSDKCustomization
• SupportedLocales

Notes

• Requires Vue >= 3.5.
• Relies on Promise.withResolvers (ES2024): Chrome/Edge 119+, Firefox 121+, Safari 17.4+. Polyfill it to support older browsers.
• Wrapper lifecycle behavior forwards to core and does not modify core semantics.
• The SDK instance is created on mount (never during setup), so the component and composable are SSR-safe: server rendering only produces the container markup. Subscriptions registered with on() during setup attach automatically once the instance exists.
• Component: config is used at instantiation time. For structural config changes, remount with a Vue :key.
• Composable: config (plain object, ref, or getter) is read each time an instance is created — on mount and again on a recreation after destroy(). A live instance does not react to config changes; call destroy() then open() to apply a new config.
• The component forces the SDK mountElement internally; do not pass mountElement in config.
• The locale prop (component) and setLocale (composable) can be called at any time, including before or while the SDK is open.