@dotgui/embed · browser

Render .gui files anywhere in the browser

@dotgui/embed renders .gui files on any website with one CDN script and one element — <gui-embed>. It is a thin layer over the kit's renderer with zero dependencies for the consumer: no build step, no framework, no install.

Quick start

One script, one element.

<script src="https://unpkg.com/@dotgui/embed"></script>

<!-- external file -->
<gui-embed src="hero.gui"></gui-embed>

<!-- inline markup — parser-safe carrier -->
<gui-embed>
  <script type="application/gui">
    <gui> … </gui>
  </script>
</gui-embed>

A src file is fetched, unzipped, its assets resolved to blob: URLs, and rendered. Inline markup lives in a <script type="application/gui"> because script content is raw text the HTML parser never touches — a full .gui survives verbatim, including tags that collide with HTML void elements like <col> and <img>.

Modes

Standalone preview or full widget — same tag.

With no CSS, the embed sizes to the file's native dimensions, like an inline SVG. Give it a width and the height follows the file's aspect ratio; give it both and the file is centered and scaled to fit. Booleans turn on widget chrome:

AttributeDefaultEffect
zoomonScroll/pinch zoom, drag-pan, and a “Fit” reset button.
gridonDot-grid canvas background — the dotgui surface.
downloadoffDownload the .gui file.
copyoffCopy the markup to the clipboard.
mode-switchoffLight/dark mode dropdown — only when the file declares more than one mode.

Programmatic

Module use and theming.

npm install @dotgui/embed

Register the element once

import { install } from '@dotgui/embed'
install() // registers <gui-embed>

The CDN build self-installs; as a module you call install() once. Theme the canvas with CSS custom properties: --gui-embed-bg, --gui-embed-dot, --gui-embed-dot-gap. The default render mode comes from the file itself.

Frequently asked

Do I need a build step or framework to use @dotgui/embed?

No. One CDN script tag registers the <gui-embed> element and bundles everything — the kit renderer, parser, package reader, pan/zoom, and unzip — into a single self-contained file with zero dependencies for the consumer.

Why does inline markup sit inside <script type="application/gui">?

Script content is raw text the HTML parser never interprets, so a complete .gui file survives verbatim — including tags like <col> and <img> that HTML would otherwise mangle as void elements. The script is also the source of truth: copy and download emit it unchanged.

How does sizing work?

Like an inline SVG. No CSS: the embed takes the file's native dimensions. Width only: height follows the file's aspect ratio. Width and height: a fixed canvas with the file centered and scaled to fit.

Can viewers switch between light and dark mode?

Yes — add the mode-switch attribute. The dropdown appears only when the file declares more than one mode; the default mode always comes from the file itself.