@viamedici-spc/configurator-framer-host
v1.5.0
Published
Provides a Web Component for host applications to embed a Framer based Viamedici SPC configurator.
Maintainers
viamediciReadme
Host Component for Framer Configurators
Introduction
This package provides a Web Component that allows host applications to embed a Framer-based Viamedici SPC configurator.
It is designed to be used in any modern web environment (e.g. plain HTML, React, Vue, etc.) and enables seamless integration to provide the best user experience.
Modes
Native Mode
In native mode, the configurator is embedded directly into the host application DOM without an iframe. This allows for tight visual and layout integration, resulting in a more seamless user experience. However, since the configurator shares the same document context as the host, styling or DOM conflicts can arise. Use this mode only when full control over the host environment is ensured.
Isolated Mode
The isolated mode, enabled via isolated="true", embeds the configurator within a sandboxed iframe. This ensures that both host and configurator remain fully decoupled, preventing style or JavaScript interference. To provide a native-feeling height behavior, the iframe automatically resizes based
on its content. This behavior can be disabled using the attribute: no-auto-height
Installation
You can install the package via npm:
npm install @viamedici-spc/configurator-framer-hostOr use it directly via a CDN (e.g. jsDelivr):
<script type="module" src="https://cdn.jsdelivr.net/npm/@viamedici-spc/[email protected]"></script>Getting Started
Below is a minimal example of how to embed a Framer configurator using the <spc-embedded-configurator> Web Component:
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<script type="module" src="https://cdn.jsdelivr.net/npm/@viamedici-spc/[email protected]"></script>
</head>
<body>
<spc-embedded-configurator src="https://example.framer.app" isolated="true"/>
</body>
</html>Attributes
Attributes for <spc-embedded-configurator>
| Attribute | Type | Description | Example |
|------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
| src | string | URL of the Framer-based configurator to embed.
| isolated | boolean | If true, the configurator runs in sandboxed iframe mode.Default: false | true, false or undefined |
| no-auto-height | boolean | if true, it disables automatic resizing of the iframe to match the configurator's content height. Only applicable when isolated mode is enabled.Default: false | true, false or undefined |
| data-* | string | Custom parameters forwarded to the configurator app (see below). | data-region="eu" |
Custom Parameters
Any attribute prefixed with data- is forwarded to the embedded configurator as a custom parameter. This lets the host
pass runtime context — for example a configuration model id, a region, or whether the configurator runs inside a webshop.
The data- prefix is stripped to form the parameter key, so data-region="eu" arrives as the parameter region with the
value "eu". Browsers lowercase attribute names, so keys are always lowercase.
<spc-embedded-configurator
src="https://example.framer.app"
data-configuration-model-id="123"
data-region="eu"
data-webshop="true"/>Parameters work identically in native and isolated (iframe) mode and hot-reload: changing an attribute at runtime
propagates to the configurator without reloading the page. The configurator reads them via the useHostParameter /
useHostParameters hooks from @viamedici-spc/configurator-framer.
Note: every
data-*attribute is treated as a parameter, including generic ones such asdata-testid.
Releasing
After publishing a new version to npm, jsDelivr may continue to serve the previous version for floating URLs (e.g. @1, @latest) for up to 12 hours per edge node, because each CDN edge caches the resolved file independently.
To make the new version available immediately on all edges and CDN providers, trigger a global purge once npm has accepted the publish:
curl -fsS "https://purge.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@1"
curl -fsS "https://purge.jsdelivr.net/npm/@viamedici-spc/configurator-framer-host@latest"License
This project is licensed under the MIT License - see the LICENSE file for details.