React SDK

The Quiltt React SDK provides Components and Hooks for seamless integration of the Quiltt Connector into your React app.

Documentation

For full documentation, additional examples and the source code, see the Quiltt React SDK on GitHub.

Link to this section#Installation

$ npm install @quiltt/react

$ pnpm add @quiltt/react

$ yarn add @quiltt/react

Link to this section#Handling Authentication

To load the Connector for use by a pre-existing end-user, you'll need to pass a valid Session token. See the Authentication guide for more information on generating Session tokens.

Link to this section#Using the Provider Component

The QuilttProvider is the easiest way to pass a Session token to your React app.

import { QuilttProvider } from '@quiltt/react'

export const App = () => {
  // See https://www.quiltt.dev/authentication/issuing-session-tokens
  const sessionToken = '<SESSION_TOKEN_FROM_SERVER>'

  return(
    <QuilttProvider token={sessionToken}>
      {children}
    </QuilttProvider>
  )
}

export default App

With the QuilttProvider handling authentication, your QuilttButton and QuilttContainer components will now automatically use the imported Session token.

Link to this section#Using the Hook

For more granular access, including the ability to read, import and revoke Session tokens, use the useQuilttSession hook.

import { useCallback, useEffect } from 'react'

import { useQuilttSession } from '@quiltt/react'

const App = () => {
  const { session, importSession, revokeSession } = useQuilttSession()

  // See https://www.quiltt.dev/authentication/issuing-session-tokens
  const sessionToken = '<SESSION_TOKEN_FROM_SERVER>'

  // Import session from API call, local storage, query param, etc.
  useEffect(() => {
    importSession(sessionToken)
  }, [importSession, sessionToken])

  console.log('Authenticated Profile ID: ', session?.sub)

  // Revoke and clear the Quiltt session
  const logOut = useCallback(() => {
    revokeSession()

    // Do other stuff...
  }, [revokeSession])

  return (
    <>
      {session && <button onClick={logOut}>Log Out</button>}
      {children}
    </>
  )
}

export default App

Link to this section#Using the Connector Hook

For programmatic control without rendering a component, use the useQuilttConnector hook to open the Connector modal imperatively.

import { useQuilttConnector } from '@quiltt/react'

export const MyComponent = () => {
  const { open } = useQuilttConnector('<CONNECTOR_ID>', {
    onExitSuccess: () => console.log('Connected!'),
  })

  return <button onClick={open}>Add Account</button>
}

export default MyComponent

Link to this section#Quickstart Examples

Link to this section#Connect with a Button

import { QuilttButton } from '@quiltt/react'

export const MyComponent = () => {
  const handleLoad = (metadata) => console.log(`Connector ${metadata.connectorId} loaded!`)
  const handleExitSuccess = (metadata) => console.log('Successfully added: ', metadata.connectionId)

  return (
    <QuilttButton
      connectorId="<CONNECTOR_ID>"
      onLoad={handleLoad}
      onExitSuccess={handleExitSuccess}
      // ... other props to pass through to the launcher <button>
    >
      Add
    </QuilttButton>
  )
}

export default App

Link to this section#Reconnect with a Button

import { QuilttButton } from '@quiltt/react'

export const MyComponent = () => {
  const handleExitSuccess = (metadata) => {
    console.log('Successfully reconnected: ', metadata.connectionId)
  }

  return (
    <QuilttButton
      connectorId="<CONNECTOR_ID>"
      connectionId="<CONNECTION_ID>"
      onExitSuccess={handleExitSuccess}
      // ... other props to pass through to the launcher <button>
    >
      Reconnect
    </QuilttButton>
  )
}

Link to this section#Prefilled Institution Search with a Button

import { QuilttButton } from '@quiltt/react'

export const MyComponent = () => {
  const handleExitSuccess = (metadata) => {
    console.log('Successfully reconnected: ', metadata.connectionId)
  }

  return (
    <QuilttButton
      connectorId="<CONNECTOR_ID>"
      institution="<SEARCH_TERM>"
      onExitSuccess={handleExitSuccess}
      // ... other props to pass through to the launcher <button>
    >
      Reconnect
    </QuilttButton>
  )
}

Link to this section#Connect Inside a Container

import { QuilttContainer } from '@quiltt/react'

export const MyComponent = () => {
  const handleLoad = () => console.log('Connector loaded!')
  const handleExitSuccess = (metadata) => console.log('Successfully added: ', metadata.connectionId)

  return (
    <QuilttContainer
      connectorId="<CONNECTOR_ID>"
      onLoad={handleLoad}
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      style={{ height: '100%' }}
      // ... other props to pass through to the container <div>
    />
  )
}

export default App

Link to this section#Reconnect Inside a Container

import { QuilttContainer } from '@quiltt/react'

export const MyComponent = () => {
  const handleExitSuccess = (metadata) => {
    console.log('Successfully reconected: ', metadata.connectionId)
  }

  return (
    <QuilttContainer
      connectorId="<CONNECTOR_ID>"
      connectionId="<CONNECTION_ID>"
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      style={{ height: '100%' }}
      // ... other props to pass through to the container <div>
    />
  )
}

export default App

Link to this section#Prefilled Institution Search Inside a Container

import { QuilttContainer } from '@quiltt/react'

export const MyComponent = () => {
  const handleExitSuccess = (metadata) => {
    console.log('Successfully reconected: ', metadata.connectionId)
  }

  return (
    <QuilttContainer
      connectorId="<CONNECTOR_ID>"
      institution="<SEARCH_TERM>"
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      style={{ height: '100%' }}
      // ... other props to pass through to the container <div>
    />
  )
}

export default App

Link to this section#Checking Provider Institution Compatibility

Use the useQuilttResolvable hook to check if external provider institution IDs (e.g., Plaid) are supported to your connector.

Contact Quiltt Support to enable access to this feature.

import { useQuilttResolvable } from '@quiltt/react'
import { useEffect } from 'react'

function ResolvableConnector({ plaidInstitutionId, children }) {
  const { checkResolvable, isResolvable, isLoading } = useQuilttResolvable('my-connector-id')

  useEffect(() => {
    checkResolvable({ plaid: plaidInstitutionId })
  }, [plaidInstitutionId])

  if (isLoading) return <div>Checking...</div>
  if (!isResolvable) return null

  return <>{children}</>
}

// Usage
<ResolvableConnector plaidInstitutionId="ins_3">
  <QuilttButton connectorId="my-connector-id">Connect through Quiltt</QuilttButton>
</ResolvableConnector>

The example above will only render the Quiltt launcher button if your Plaid-enabled Connector supports connecting to Chase.

Link to this section#Component Props

Shared props for QuilttButton, QuilttContainer, and useQuilttConnector:

Prop	Type	Description
`connectorId`	string	Required. Quiltt Connector ID
`connectionId`	string	Existing connection ID for reconnection
`institution`	string	Pre-select an institution
`themeMode`	`'light'` \| `'dark'` \| `'auto'`	Theme mode for the Connector UI. Defaults to `'light'`
`appLauncherUrl`	string	Deep link URL for OAuth callbacks
`nonce`	string	CSP nonce for the script tag when using strict Content Security Policy
`forceRemountOnConnectionChange`	boolean	Forces complete remount when `connectionId` changes. Defaults to `false`
`onEvent`	`(eventType, metadata) => void`	Intermediate Connector event
`onLoad`	`(metadata) => void`	Connector loaded
`onExit`	`(eventType, metadata) => void`	Connector exited via an event
`onExitSuccess`	`(metadata) => void`	Connection successful
`onExitAbort`	`(metadata) => void`	User cancelled
`onExitError`	`(metadata) => void`	Error occurred

QuilttButton additionally supports onOpen (called just before the connector opens) and as (to render as a different element type).

For better tree-shaking, components can also be imported from subpaths:

import { QuilttButton } from '@quiltt/react/components'
import { useQuilttSession } from '@quiltt/react/hooks'

Link to this section#TypeScript

The React package comes bundled with the @quiltt/core package, which contains type definitions for all components and hooks.

See the definition file on GitHub

Link to this section#Next.js

For developers looking to quickly bootstrap a Next.js project with Quiltt integration, we offer a pre-configured template:

Quiltt Next.js Template

This template provides a solid foundation for building fintech applications with Quiltt and Next.js. It includes:

Next.js 14 with App Router
TypeScript for type safety
Quiltt React SDK integration
GraphQL code generation for Quiltt API
Authentication flow (Login and Signup)
Tailwind CSS for styling

To get started with the template, clone the repository and follow the setup instructions in the README. This can significantly speed up your development process and ensure you're following best practices for Quiltt integration from the start.

← iOS

React Native→