@vitable-inc/drops

Drop-in benefits enrollment and administration components for your application.

Vitable Drops provides pre-built React components that embed fully functional benefits experiences — employee enrollment dashboards, qualifying life event flows, and employer administration views — directly into your app via secure iframes.

Documentation

Installation

npm install @vitable-inc/drops

Quick Start

Wrap your app with the VitableConnectProvider and drop in a widget:

import { VitableConnectProvider, EmployeeViewWidget } from "@vitable-inc/drops/react"

function App() {
  const fetchToken = async () => {
    const res = await fetch("/api/vitable/token")
    return res.json() // { token: string, expiresIn: number }
  }

  return (
    <VitableConnectProvider baseUrl="https://app.vitablehealth.com" fetchToken={fetchToken}>
      <EmployeeViewWidget
        onEnrollmentComplete={enrollments => console.log("Enrolled:", enrollments)}
        onError={(code, message) => console.error(code, message)}
      />
    </VitableConnectProvider>
  )
}

Components

VitableConnectProvider

Required context provider that manages authentication and configuration.

<VitableConnectProvider
  baseUrl="https://app.vitablehealth.com"
  fetchToken={fetchToken}
  allowedOrigins={["https://app.vitablehealth.com"]} // optional, derived from baseUrl by default
  contextKey={employeeId} // optional, re-keys widgets when switching entities
  onError={(code, message) => {}}
/>

EmployeeViewWidget

Embeds the employee benefits dashboard — enrollment, plan selection, and management.

<EmployeeViewWidget
  width="100%"
  height="600px"
  onReady={() => {}}
  onEmployeeViewReady={() => {}}
  onEnrollmentComplete={enrollments => {}}
  onQleSubmitted={eventType => {}}
  onAppointmentScheduled={visitReasonName => {}}
  onTokenExpired={() => {}}
  onAuthError={(code, message) => {}}
  onError={(code, message) => {}}
/>

EmployerBenefitsWidget

Embeds the employer benefits administration view.

<EmployerBenefitsWidget
  width="100%"
  height="600px"
  onReady={() => {}}
  onEmployerBenefitsReady={() => {}}
  onTokenExpired={() => {}}
  onAuthError={(code, message) => {}}
  onError={(code, message) => {}}
/>

Token Provider

Your fetchToken callback must return an object with:

interface AccessTokenResponse {
  token: string // OAuth2 access token
  expiresIn: number // Seconds until expiration
}

The SDK handles token lifecycle automatically — initial fetch, proactive refresh before expiry, and re-fetch on expiration.

Core Module

For advanced use cases or non-React environments, the core module exposes the underlying PostMessage protocol:

import { createMessage, parseVitableConnectMessage } from "@vitable-inc/drops/core"

Requirements

• React 18 or 19 (peer dependency)

License

Apache-2.0