RuleCMS Widget Integration - HTML Demo

A demonstration of how to embed RuleCMS widgets in any HTML page using the <rulecms-widget> custom element. No React, Vue, Angular, or other host framework. No npm package in the page — one script tag from RuleCMS is enough.

View the live demo

Experience the RuleCMS HTML embed without running the page locally.

RuleCMS is a visual content management system that lets you:

• Build widgets visually using a drag-and-drop composer
• Create responsive content that works across devices
• Publish instantly and get a unique published key for each widget
• Embed those widgets in any HTML page with a script tag and a custom element

1. Design — Log into rulecms.com and compose a widget.
2. Publish — RuleCMS generates a published key ({environmentId}---widget-…).
3. Authenticate — Create an app token in project settings so the page can fetch published widgets.
4. Embed — Load the embed script and place <rulecms-widget> with your token and published key.

The script served from https://rulecms.com/embed/… registers the custom element and already includes the default RuleCMS cards (text, image, video, and the rest of the shipped set). Your page does not install @rulecms/widget-react or register a component library.

git clone https://github.com/rulecms/use_rulecms_example_html_project.git
cd use_rulecms_example_html_project
npm install
npm start

The page is at http://localhost:5173. Demo credentials on the <rulecms-widget> tag in index.html are enough to render the widget without extra setup. Or skip local setup and use the live demo.

Vite is only here so this teaching repo can be previewed locally and deployed to Vercel. A production host does not need Vite — copy the script tag and custom element into any HTML file.

Prefer the versioned URL in production so a new release cannot change your page unexpectedly:

<script src="https://rulecms.com/embed/widget-custom-element@0.2.0/widget-custom-element.iife.js"></script>

Optional always-latest URL (short cache):

<script src="https://rulecms.com/embed/widget-custom-element/latest/widget-custom-element.iife.js"></script>

<rulecms-widget
  token="your-app-token"
  published-key="your-published-key"
></rulecms-widget>

App token

1. Log into rulecms.com
2. Open project settings → API / app tokens
3. Generate a token with widget access

Published key

1. Create or edit a widget in the composer
2. Click Publish
3. Copy the generated published key

npm start

Demo values are attributes on <rulecms-widget> in index.html (same widget and token as the React, Vue, Angular, and Svelte examples):

• token — app token used to fetch the widget
• published-key — published key for the demo widget

Replace those attributes with your own token and published key when you wire this up to your site.

Attributes

• token (required): app token from RuleCMS project settings
• published-key (required): {environmentId}---widget-… for staging/production, or a draft widget-… key with a dev. token
• endpoint (optional): API origin override. Leave unset so published tokens hit widget-cache and dev. tokens hit rulecms.com

The script chooses the API host from the token. You do not set endpoint in production.

Load the script once, then place as many custom elements as the page needs:

<script src="https://rulecms.com/embed/widget-custom-element@0.2.0/widget-custom-element.iife.js"></script>

<header>
  <rulecms-widget token="your-app-token" published-key="header-key"></rulecms-widget>
</header>
<main>
  <rulecms-widget token="your-app-token" published-key="main-key"></rulecms-widget>
</main>

After the script loads, window.RuleCMS can mount into an existing node:

<div id="hero-slot"></div>
<script src="https://rulecms.com/embed/widget-custom-element@0.2.0/widget-custom-element.iife.js"></script>
<script>
  RuleCMS.mount(document.getElementById('hero-slot'), {
    token: 'your-app-token',
    publishedKey: 'your-published-key',
  });
</script>

This demo uses the declarative custom element so npm start is enough.

The same two tags work anywhere you can add HTML:

• WordPress: enqueue the script (or a header/footer plugin), then a Custom HTML block for <rulecms-widget>
• PHP / Rails / any CMS: print the script once and output the element with escaped token and key values
• Webflow / static hosts: paste both tags into an embed / custom-code block

See HTML Custom Element Embed for WordPress and Angular-shell notes.

Widget not displaying

• Confirm token and published-key on <rulecms-widget> in index.html
• Confirm the embed script returns HTTP 200 from rulecms.com/embed/…
• Check the browser console

Error loading widget / 401

• Wrong or disabled token, or the token environment does not match the published key

Custom team components missing

• The HTML embed ships the default card library. For custom libraries, use @rulecms/widget-react in a React host

use_rulecms_example_html_project/
├── index.html       # Script tag + <rulecms-widget>
├── styles.css
├── package.json     # Vite only — not required on a customer site
├── vercel.json
└── README.md

• RuleCMS: rulecms.com
• Docs: HTML Custom Element Embed
• @rulecms/widget-custom-element

MIT