JavaScript SDK (`@orderly/embed-js`)

Vanilla JavaScript SDK for any framework or plain HTML. Uses Shadow DOM for style isolation.

Installation

npm


npm install @orderly/embed-js

CDN


<script src="https://cdn.orderly.dev/embed.min.js"></script>

Quick Start

ES Modules


import { OrderlyConnect } from '@orderly/embed-js'
 
const connect = OrderlyConnect({
  fetchClientSecret: () =>
    fetch('/api/orderly/session', { method: 'POST' })
      .then(r => r.json())
      .then(d => d.clientSecret),
  onBridgeCreated: (bridge) => console.log('Created:', bridge),
})
 
connect.mount('#orderly-container')

CDN / Script Tag


<div id="orderly-container"></div>
<script src="https://cdn.orderly.dev/embed.min.js"></script>
<script>
  const connect = OrderlyEmbed.OrderlyConnect({
    fetchClientSecret: () =>
      fetch('/api/orderly/session', { method: 'POST' })
        .then(r => r.json())
        .then(d => d.clientSecret),
    onBridgeCreated: (bridge) => console.log('Created:', bridge),
  })
  connect.mount('#orderly-container')
</script>

This requires a server-side endpoint that creates sessions using @orderly/node or the Java SDK.

`OrderlyConnect(options)`

Creates an embed instance. Returns an object with mount, unmount, update, and destroy methods.

Options

Option	Type	Required	Description
`fetchClientSecret`	`() => Promise<string>`	Yes	Returns an `est_` token from your server
`mode`	`'full' \| 'connect'`	No	Display mode
`slug`	`string`	No	Branding slug
`appearance`	`EmbedAppearance`	No	Visual overrides
`allowedBridgeTypes`	`string[]`	No	Restrict available bridge types
`embedOrigin`	`string`	No	Override embed origin URL
`onReady`	`() => void`	No	Embed loaded
`onBridgeCreated`	`(bridge) => void`	No	Bridge created
`onBridgeUpdated`	`(bridge) => void`	No	Bridge updated
`onBridgeDeleted`	`(bridge) => void`	No	Bridge deleted
`onError`	`(error) => void`	No	Error occurred
`onResize`	`(height) => void`	No	Iframe height changed

Instance Methods

`mount(target)`

Mount the embed into a DOM element. Accepts a CSS selector string or an HTMLElement.


// CSS selector
connect.mount('#container')
 
// DOM element
const el = document.getElementById('container')
connect.mount(el)

`unmount()`

Remove the embed from the DOM. The instance can be re-mounted later.


connect.unmount()

`update(options)`

Update options without remounting. Appearance changes are pushed to the iframe immediately.


connect.update({
  appearance: { primaryColor: '#ef4444' },
})

`destroy()`

Fully destroy the instance and clean up all event listeners. Cannot be re-mounted after this.


connect.destroy()

Session Refresh

Session refresh is automatic. When the session is about to expire, the SDK calls fetchClientSecret again and sends the new token to the iframe.

Shadow DOM

The SDK renders inside a Shadow DOM for style isolation. Your page’s CSS won’t affect the embed, and the embed’s styles won’t leak into your page. The iframe auto-resizes to match its content height.

Vue.js Example


<template>
  <div ref="container" />
</template>
 
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { OrderlyConnect } from '@orderly/embed-js'
 
const container = ref(null)
let connect = null
 
onMounted(() => {
  connect = OrderlyConnect({
    fetchClientSecret: () =>
      fetch('/api/orderly/session', { method: 'POST' })
        .then(r => r.json())
        .then(d => d.clientSecret),
  })
  connect.mount(container.value)
})
 
onUnmounted(() => {
  connect?.destroy()
})
</script>

Angular Example


import { Component, ElementRef, OnDestroy, OnInit, ViewChild } from '@angular/core'
import { OrderlyConnect, type EmbedInstance } from '@orderly/embed-js'
 
@Component({
  selector: 'app-integrations',
  template: '<div #container></div>',
})
export class IntegrationsComponent implements OnInit, OnDestroy {
  @ViewChild('container', { static: true }) container!: ElementRef
 
  private embed: EmbedInstance | null = null
 
  ngOnInit() {
    this.embed = OrderlyConnect({
      fetchClientSecret: () =>
        fetch('/api/orderly/session', { method: 'POST' })
          .then(r => r.json())
          .then(d => d.clientSecret),
    })
    this.embed.mount(this.container.nativeElement)
  }
 
  ngOnDestroy() {
    this.embed?.destroy()
  }
}

JavaScript SDK (@orderly/embed-js)