Logo
ProductsDesignNewsSupport
Account
Mono Card User Guide

Mono Card JavaScript SDK

A lightweight JavaScript SDK for embedding and controlling Mono Card templates in your web applications.

Features

  • 🎨 40+ customizable card templates
  • 🔄 Real-time content updates
  • 📦 Zero dependencies & Framework agnostic
  • 🚀 Easy to integrate

Installation

npm install mono-card
# or
pnpm add mono-card

Quick Start

<!DOCTYPE html>
<html>
  <head>
    <title>Mono Card SDK Example</title>
  </head>
  <body>
    <div id="card-container"></div>

    <script src="https://unpkg.com/monocard-sdk@latest/monocard-sdk.js"></script>
    <script>
      // Initialize MonoCard
      const cardEditor = new MonoCard({
        root: document.getElementById("card-container"),
        template: "modern",
        lang: "en",
        width: "100%",
        height: "600px",
      });

      // Update card content
      cardEditor.setTitle("My Awesome Card");
      cardEditor.setBody("This is the card description");
      cardEditor.setAuthor("John Doe");
      cardEditor.setImage("https://example.com/image.jpg");

      // Customize appearance
      cardEditor.setBackground("gradient");
      cardEditor.setDropShadow("even");
      cardEditor.showQRCode(true);
    </script>
  </body>
</html>

API Reference

Constructor

new MonoCard(options)

Creates a new MonoCard instance and embeds an iframe into the specified container.

Parameters:

OptionTypeRequiredDefaultDescription
rootHTMLElementYes-DOM element to embed the iframe
templatestringYes-Template ID (e.g., 'apple', 'googlesearch', 'modern')
langstringNo'en'Language code ('en', 'zh', 'jp')
baseUrlstringNo'https://monocard.app'Base URL for iframe
initialDataobjectNoInitial card data
widthstringNo'100%'Iframe width
heightstringNo'600px'Iframe height

Example:

const card = new MonoCard({
  root: document.getElementById("container"),
  template: "modern",
  lang: "en",
  initialData: {
    title: "Welcome",
    body: "Initial content",
  },
});

Content Methods

setTitle(title: string)

Set the card title.

cardEditor.setTitle("My Card Title");

setBody(body: string)

Set the card body content. Supports markdown.

cardEditor.setBody("This is **bold** text");

setAuthor(author: string)

Set the card author name.

cardEditor.setAuthor("Jane Smith");

setImage(url: string)

Set the card image. Accepts URL or base64 string.

cardEditor.setImage("https://example.com/image.jpg");

setIcon(url: string)

Set the card icon. Accepts URL or base64 string.

cardEditor.setIcon("https://example.com/icon.png");

setQRCode(data: string)

Set QR code data or URL.

cardEditor.setQRCode("https://monocard.app");

setSourceUrl(url: string)

Set the source URL for the card.

cardEditor.setSourceUrl("https://example.com");

Customization Methods

setBackground(background: string)

Set the background style.

Options: 'milky', 'dim', 'gradient', 'none'

cardEditor.setBackground("gradient");

setDropShadow(shadow: string)

Set the drop shadow style.

Options: 'none', 'even', 'directional'

cardEditor.setDropShadow("even");

setShadowOverlay(overlay: string)

Set the shadow overlay effect.

Options: 'tree', 'leafy', 'palm', 'none'

cardEditor.setShadowOverlay("tree");

setShadowStrength(strength: number)

Set shadow strength (0-100).

cardEditor.setShadowStrength(75);

showQRCode(show: boolean)

Show or hide the QR code.

cardEditor.showQRCode(true);

Template Control

setTemplate(template: string)

Switch to a different template dynamically.

cardEditor.setTemplate("googlesearch");

Batch Updates

updateCard(data: object)

Update multiple properties at once for better performance.

cardEditor.updateCard({
  cardData: {
    title: "New Title",
    body: "New body content",
    author: "New Author",
    image: "https://example.com/new-image.jpg",
  },
  customizeData: {
    background: "gradient",
    dropShadow: "even",
    showQRCode: true,
  },
  template: "modern",
});

Utility Methods

getIframeUrl(): string

Get the current iframe URL with all parameters.

const url = cardEditor.getIframeUrl();
console.log(url);

destroy()

Remove the iframe and cleanup event listeners.

cardEditor.destroy();

Event Callbacks

onReady

Called when the iframe is ready to receive updates.

cardEditor.onReady = () => {
  console.log("Card is ready!");
  cardEditor.setTitle("Ready!");
};

onUpdate

Called when the iframe confirms a data update.

cardEditor.onUpdate = (data) => {
  console.log("Card updated:", data);
};

Troubleshooting

Card Not Displaying

  • Ensure the root element exists in the DOM before initializing
  • Check browser console for errors
  • Verify the template ID is valid

Updates Not Working

  • Wait for onReady callback before sending updates
  • Check that postMessage is not blocked by CSP
  • Verify the iframe has loaded successfully

CORS Issues

  • The SDK communicates via postMessage, which works cross-origin
  • Ensure your Content Security Policy allows iframe embedding
Was this page helpful?