Custom Connection UI - Membrane Docs

You can open the prebuilt connection UI for a specific integration with:

await membrane.ui.connect({ integrationKey: 'hubspot' })

This guide shows you how you can implement a custom connection UI

1. Get Auth Options

To get information about what to ask the user in order to create a connection, fetch connection options:

const integration = await membrane.integration('hubspot').get()

// Fetch connection options
const connectionOptions = await membrane.post('/connection-options', {
  integrationId: integration.id,
})

For simplicity, we’ll assume there is only one auth option. If there are more, you can use the same logic for each of them. If there are zero options, it means authentication is not configured and you need to edit or change the connector. Each connection option contains:

key – Unique identifier for this auth option (pass to authOptionKey when connecting)
type – The authentication type (e.g., ‘oauth2’, ‘client-credentials’)
title – Human-readable name for this auth option
description – Description explaining this auth method
inputSchema – Data Schema of the parameters required to create a connection. It will be empty if parameters are not required.

2. Connection Parameters UI

You can use your preferred way of converting JSON Schema into a form. For example, you can extract a list of fields from the schema and simply display an input for each:

function ConnectionForm() {
  const [input, setInput] = useState({})

  const schema = {
    type: 'object',
    properties: {
      email: { type: 'string' },
      apiKey: { type: 'string' },
    },
  }

  const fields = Object.keys(schema.properties)

  return (
    <>
      {fields.map((field) => (
        <div key={field}>
          <label>{field}</label>
          <input
            type='text'
            className='p-1 border rounded'
            value={input[field] || ''}
            onChange={(e) => setInput({ ...input, [field]: e.target.value })}
          />
        </div>
      ))}
    </>
  )
}

If a connection doesn’t have parameters, you can skip this step.

3. Creating a Connection

When you have collected connection input, you can create a connection:

const connection = await membrane.integration('hubspot').connect({ input })

This code may open a new window if it is required by the authentication process. Make sure this code runs inside a user action handler (e.g. onClick), otherwise the browser may block the new window.

Redirect instead of a new window When you need to avoid opening a new window, you can use redirect instead. Pass sameWindow: true and redirectUri options. The URI will be used for redirection after the connection is created or fails. Added query parameters:

For successful creation, the connectionId will be added
For failures, error will contain the error message and errorData will contain the JSON stringified error payload

const connection = await membrane.integration('hubspot').connect({
  input,
  sameWindow: true,
  redirectUri: window.location.href,
})

4. Putting it all together

Here is a simple UI component that displays the connection parameters and creates a new connection:

import { useState, useEffect } from 'react'
import { useIntegration, useMembrane } from '@membranehq/react'

function Component({ integrationKey }) {
  // For this to work, wrap this component in <MembraneProvider/>
  const membrane = useMembrane()

  const { integration, error } = useIntegration(integrationKey)

  const [connectionOptions, setConnectionOptions] = useState(null)
  const [connectionInput, setConnectionInput] = useState({})
  const [connecting, setConnecting] = useState(false)
  const [connection, setConnection] = useState(null)

  // Fetch connection options
  useEffect(() => {
    if (!integration?.id) return

    membrane
      .post('/connection-options', {
        integrationId: integration.id,
      })
      .then(setConnectionOptions)
  }, [integration?.id, membrane])

  // If something bad happened - show the error
  if (error) {
    return <p>Error: {error.message}</p>
  }

  // Wait until the spec and connection options load
  if (!integration || !connectionOptions) {
    return <p>Loading...</p>
  }

  // Display only the first option
  const option = connectionOptions[0]

  if (!option) {
    return <p>No auth options found for this integration</p>
  }

  // Get connection input schema
  const schema = option.inputSchema

  // Simplified way to get the list of connection parameters.
  const fields = schema ? Object.keys(schema.properties ?? {}) : []

  async function connect() {
    setConnecting(true)
    try {
      const connection = await membrane.integration(integrationKey).connect({
        input: connectionInput,
        authOptionKey: option.key,
      })
      setConnection(connection)
    } finally {
      setConnecting(false)
    }
  }

  return (
    <div>
      {fields.length > 0 && (
        <div>
          <strong>Connection Parameters:</strong>
          {fields.map((field) => (
            <div key={field}>
              <label>{field}</label>
              <input
                type='text'
                value={connectionInput[field] || ''}
                onChange={(e) =>
                  setConnectionInput({
                    ...connectionInput,
                    [field]: e.target.value,
                  })
                }
              />
            </div>
          ))}
        </div>
      )}

      {connecting ? <span>Connecting...</span> : <button onClick={connect}>Connect</button>}

      {connection && (
        <div>
          <strong>Connected!</strong>
          <br />
          Connection Id: {connection.id}
        </div>
      )}
    </div>
  )
}

5. Re-connecting

When a connection becomes disconnected, you can re-connect it using the same code as when creating a new connection:

const connection = await membrane.integration('hubspot').connect({ input })

Creating or updating connections

Every completed connect(...) flow creates a new connection when you target an integration (integrationId / integrationKey), connector (connectorId / connectorKey), or external app (externalAppId / externalAppKey). To re-authenticate or update an existing connection in place, pass its connectionId. That is the only path that writes fresh credentials to an existing connection record.

​1. Get Auth Options

​2. Connection Parameters UI

​3. Creating a Connection

​4. Putting it all together

​5. Re-connecting

​Creating or updating connections