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;targetis 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">withoptions.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
Modal behaviour
- 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.
| Class | Element |
|---|---|
.cp-button | The button rendered by mount() into an empty target |
#coverport-overlay | The fixed backdrop |
#coverport-overlay .cp-frame-wrap | The white card that holds the iframe |
#coverport-overlay .cp-close | The 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.
| Attribute | Maps to |
|---|---|
data-coverport-key | key |
data-coverport-product | product |
data-coverport-button-text | buttonText |
data-coverport-primary | theme.primary |
data-coverport-secondary | theme.secondary |
data-coverport-mode | theme.mode |
data-coverport-logo | theme.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-jswithout 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
integrityandcrossorigin="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.crossoriginis 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 -Aand prefix the output withsha384-.
| Version | URL | integrity |
|---|---|---|
| 0.2.0 | https://unpkg.com/@cargolabs/coverport-js@0.2.0/dist/coverport.iife.js | sha384-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 |
| Formats | ESM (import), CommonJS (require), IIFE (unpkg script tag) |
| Types | Bundled .d.ts |
| Runtime dependencies | None |
| Side effects | None in the ESM/CJS build. The IIFE build auto-mounts on load. |
| Licence | MIT |