CoverPort API and SDK are in beta. Endpoints and the embed may change without notice, and sales should be reconciled in the developer portal. Report problems to support@coverport.io.
CargoLabs Docs

Reference

The complete @cargolabs/coverport-js surface. Two functions, one options object, no runtime dependencies.

import coverport, { mount, open } from '@cargolabs/coverport-js';
import type { CoverportOptions, MountOptions, CoverportHandle, CoverportSale } from '@cargolabs/coverport-js';

The default export is { mount, open }. Named exports are also available. The script-tag build exposes the same object as window.coverport.

coverport.mount(target, options)

Renders a quote button into target and wires it to open the flow.

function mount(target: string | HTMLElement, options: MountOptions): CoverportHandle;
  • target is a CSS selector or an element. Throws if the selector matches nothing.
  • If the target is empty, the SDK appends a styled <button class="cp-button"> with options.buttonText.
  • If the target already has content (your own button, a link, an icon), it is left untouched and a click listener is attached to it.

Returns a handle:

Prop

Type

coverport.open(options)

Opens the modal immediately. Use it from your own event handlers.

function open(options: CoverportOptions): () => void;

Returns a function that closes the modal. Only one modal exists at a time: calling open while one is showing replaces it.

Options

CoverportOptions is accepted by both functions. MountOptions extends it with buttonText.

Prop

Type

CoverportSale

Passed to onComplete.

Prop

Type

  • Fixed overlay at z-index: 2147483000, backdrop click and Escape both close it.
  • Focus moves into the flow when the modal opens and returns to the element that opened it when it closes (0.1.2 and later).
  • The dialog is role="dialog" aria-modal="true" with an accessible label.
  • Frame is 480px wide and min(720px, 92vh) tall; on small screens it fills the viewport minus 16px padding.
  • Animations respect prefers-reduced-motion.
  • The iframe is created with allow="payment" so the Payment Request API works inside it.

CoverportTheme

Passed as options.theme. Every field is optional; what you set here wins over the key's defaults from the developer portal.

Prop

Type

Styling

The SDK injects one <style id="coverport-styles"> block. You can override any of these classes from your own stylesheet; load yours after the SDK or increase specificity.

ClassElement
.cp-buttonThe button rendered by mount() into an empty target
#coverport-overlayThe fixed backdrop
#coverport-overlay .cp-frame-wrapThe white card that holds the iframe
#coverport-overlay .cp-closeThe close button

If you want full control over the button, give the mount target your own markup and the SDK will not render one.

Script-tag data attributes

When loaded with the script tag, every element with data-coverport-key is mounted on DOMContentLoaded (or immediately if the DOM is already ready). Elements are marked data-coverport-mounted="true" so re-running the script is idempotent.

AttributeMaps to
data-coverport-keykey
data-coverport-productproduct
data-coverport-button-textbuttonText
data-coverport-primarytheme.primary
data-coverport-secondarytheme.secondary
data-coverport-modetheme.mode
data-coverport-logotheme.logo

Callbacks cannot be expressed as attributes. To use onComplete with the script tag, call window.coverport.mount(…) or window.coverport.open(…) yourself instead of relying on auto-mount.

Script tag: version and integrity

Load a pinned version by its exact file, with a Subresource Integrity hash:

<script
  src="https://unpkg.com/@cargolabs/coverport-js@0.2.0/dist/coverport.iife.js"
  integrity="sha384-OoTnysigfpG1on38z5//WHt0MgwHKFiVkGDg/r26PrHlgKLgBGuAdtqDz20yKtGP"
  crossorigin="anonymous"
></script>
  • Pin the version. https://unpkg.com/@cargolabs/coverport-js without a version follows the latest release, so a new release reaches your page without you deciding to take it, and an integrity hash on it breaks as soon as a new version is published.
  • Keep integrity and crossorigin="anonymous" together. The browser hashes the downloaded file and refuses to run it if it does not match, so a compromised CDN or package cannot run other code on your page. crossorigin is required for the check on a cross-origin script.
  • Upgrading: change the version in the URL and the hash together. Each release's hash is listed here; to check it yourself, run curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A and prefix the output with sha384-.
VersionURLintegrity
0.2.0https://unpkg.com/@cargolabs/coverport-js@0.2.0/dist/coverport.iife.jssha384-OoTnysigfpG1on38z5//WHt0MgwHKFiVkGDg/r26PrHlgKLgBGuAdtqDz20yKtGP

If you self-host the file (for example to avoid https://unpkg.com in your script-src), copy dist/coverport.iife.js from the npm package; the same hash applies.

Package details

Package@cargolabs/coverport-js
FormatsESM (import), CommonJS (require), IIFE (unpkg script tag)
TypesBundled .d.ts
Runtime dependenciesNone
Side effectsNone in the ESM/CJS build. The IIFE build auto-mounts on load.
LicenceMIT

On this page