Quick start

Release 0.1.0-beta.1 · API 1.0-beta · Source-available license 1.0

Choose one route below. Each uses the immutable 0.1.0-beta.1 files, without a package install. The examples load the bundled public inverter project. Unresolved component models use labelled stand-ins.

Classic script

Save this as a webpage on an HTTP(S) host. Give the mount a real height; an empty container with no height cannot show the drawing.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Interactive board</title>
<div id="board" style="width:100%;height:70dvh;min-height:360px"></div>
<p id="status" role="status">Opening design…</p>
<script src="https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/kicad-webview.min.js"></script>
<script>
const viewer = new KiCadWebView.Viewer('#board', { theme: 'dark' });
viewer.addEventListener('error', event => {
  document.querySelector('#status').textContent = event.detail.message;
});
viewer.load(
  'https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/demo/project.json',
  { view: '3d' }
).then(loaded => {
  if (loaded) document.querySelector('#status').textContent = 'Read-only project';
}).catch(error => {
  document.querySelector('#status').textContent = error.message;
});
window.addEventListener('pagehide', () => viewer.dispose(), { once: true });
</script>
</html>

Open the supplied classic-script example. Replace the sample URL with your supported hosted drawing, project manifest or ZIP. Attach event listeners before calling load.

ES module

Use the same container, then replace the classic scripts with this module. The filename kivi-viewer.js is the supplied full ES-module entry.

<script type="module">
import { Viewer } from 'https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/kivi-viewer.js';

const viewer = new Viewer('#board', { theme: 'dark' });
window.addEventListener('pagehide', () => viewer.dispose(), { once: true });
try {
  await viewer.load(
    'https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/demo/project.json',
    { view: '3d' }
  );
} catch (error) {
  document.querySelector('#status').textContent = error.message;
}
</script>

Use an HTTP(S) page rather than opening a module page directly with file://. Cross-origin modules and design files need appropriate CORS responses. See hosting.

iframe

Use this route when the host accepts HTML iframes but does not permit your own page scripts.

<iframe
  title="Interactive inverter design"
  src="https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/embed.html?src=demo%2Fproject.json&amp;view=3d&amp;theme=dark"
  style="width:100%;height:70dvh;min-height:360px;border:0"
  loading="lazy">
</iframe>

The relative src design URL resolves against embed.html, not the parent webpage. For another host’s design, encode an absolute source URL. The iframe parameter reference describes the supported options; this release does not provide a general cross-origin iframe command bridge.

Self-host the ZIP

1. Download the complete release ZIP.
2. Unpack it and keep the release files, LICENSE, notices and licenses/ together. Preserve relative paths.
3. Serve the directory through your approved static HTTP(S) host. No runtime Node service is required.
4. Open direct.html, embed.html with a source parameter, or export.html.
5. Point your application’s script/import URLs at your versioned copy. Do not change bytes under an already published release version.

The release manifest supplies SHA-256 file checksums and a classic-script SRI value. Keep the entire release when you need all entry points. A smaller integration still needs the dependencies and notices required by the files it uses.

Export a self-contained HTML viewer

Open the browser-only exporter, choose local design files or one project ZIP, select an initial view and create the HTML download. Include saved model assets in a project ZIP with their expected paths. The exporter reads your chosen files locally; it does not upload the design.

The output contains your design, viewer and notices. Review it before sharing. Its content policy blocks external network connections, so missing models cannot be fetched later. A recipient’s browser or host application must allow interactive HTML and WebGL for 3D.

Open the bundled inverter HTML for a ready-made example. The export API is a separate module; it is not a method on the KiCadWebView global.

Next steps

Use the user guide for controls and interpretation, the examples for application patterns, and the API reference for signatures, options and cleanup. Check license 1.0 before commercial use.