@antglobal/copilot-cards-web

Web renderer for schema-driven cards in AI conversations. It turns one JSON schema into interactive Custom Elements for desktop browsers, mobile browsers, and WebViews.

The package includes the core schema and action APIs, responsive rendering, Shadow DOM style isolation, streaming updates, and extensible component registration.

Installation

npm install @antglobal/copilot-cards-web

@antglobal/copilot-cards-core is installed automatically.

Quick start

import { renderCard } from "@antglobal/copilot-cards-web";

const container = document.getElementById("card");
if (!container) throw new Error("Missing #card container");

const schema = {
  version: "1.0",
  rootID: "root",
  elements: {
    root: {
      id: "root",
      type: "Text",
      props: {
        content: { type: "static", value: "Hello, Copilot Cards!" },
      },
    },
  },
  variables: {},
};

const card = renderCard(container, schema, {
  emit: (eventName, payload) => {
    console.log(eventName, payload);
  },
  showToast: (message, level) => {
    console.log(`[${level ?? "info"}] ${message}`);
  },
});

card.updateVariables({ userName: "Alice" });

// Dispose when the host view is removed.
card.dispose();

Framework usage

The renderer accesses browser APIs and should be loaded on the client in frameworks that perform server-side rendering.

const { renderCard } = await import("@antglobal/copilot-cards-web");

In React or Next.js, run the dynamic import inside a client component effect. In Vue, run it after the component is mounted.

Main API

renderCard(container, schema, options?)

Renders a complete schema and returns a CardInstance:

interface CardInstance {
  updateVariables(variables: Record<string, unknown>): void;
  dispose(): void;
}

Common render options include:

| Option | Purpose | | --- | --- | | variables | Overrides initial schema variables | | botId | Selects bot-scoped custom action handlers | | isMobile | Overrides automatic viewport detection | | fetch | Supplies a custom request implementation | | showToast | Connects toast actions to the host UI | | navigate | Connects URL actions to host navigation | | emit | Receives events emitted by a card | | copyText | Connects copy actions to the host clipboard |

Streaming

Use renderStreamingCard when the card arrives incrementally from an AI model or server:

import { renderStreamingCard } from "@antglobal/copilot-cards-web";

const stream = renderStreamingCard(container);

stream.feed(chunk);
stream.flush();
stream.dispose();

The package also exports connectStreaming and connectSSE helpers, plus partial-schema and A2UI adapters.

BotSDK

BotSDK groups card instances, bot-scoped action handlers, and declarative action providers behind one host-facing API.

import { BotSDK } from "@antglobal/copilot-cards-web";

const bot = new BotSDK({
  botId: "support-bot",
  onAction: {
    trackEvent: async (step) => {
      console.log(step.params);
    },
  },
});

await bot.renderCard(container, schema);

Built-in components

The renderer includes:

• Text, Button, Input, Image, Divider
• Rate, Tag, Select, PasscodeInput
• Icon, Form, Loading, Progress
• Steps, Collapse, and sanitized HTML

Components render as isolated ai-card-* Custom Elements.

Custom components

import {
  registerComponent,
  type ComponentRenderer,
} from "@antglobal/copilot-cards-web";

const renderStatus: ComponentRenderer = (_node, props) => {
  const element = document.createElement("div");
  element.textContent = String(props.label ?? "");
  return element;
};

registerComponent("Status", renderStatus);

Actions

Cards can declaratively request emit, request, setVariable, toast, url, and copy actions. The host remains in control of network access, navigation, notifications, clipboard behavior, and custom business actions.

Browser requirements

• Custom Elements
• Shadow DOM
• AbortController
• Modern JavaScript with ES2020 support

Provide appropriate polyfills when targeting older WebViews.

Related packages

• @antglobal/copilot-cards-core — UI-independent schema, expression, action, lifecycle, and streaming logic.
• @antglobal/copilot-cards-mini-program — native renderer for Alipay and WeChat mini-programs.

License

MIT