v0.4.0GitHub—

docs / guides / element

HTML custom element

Configure Swarm Troopers declaratively in any template language.

##Register once

The classic IIFE registers the element automatically. With package modules, import its separate entry once in client code:

javascript
import 'swarmtroopers/element';

html
<main>
  <h1>Your existing page</h1>
</main>
<swarmtroopers-overlay auto inspect tokens controls root="main"></swarmtroopers-overlay>

The element is configuration, not a wrapper. It hides itself and targets content elsewhere through root. Keep content outside it. Connection creates one instance after DOM readiness; disconnection destroys that instance.

##Supported attributes

AttributeValue / defaultEffect
rootSelector; body if absentTarget content root.
selector[data-swarmtroopers]Annotation selector.
autoAbsent = falseAutomatic scanning when present and not "false".
inspectAbsent = falseEnable finished-element inspection.
tokensAbsent = falseInstall the built-in tokens plugin.
controlsAbsent = no controlsEnable controls; an optional corner value sets position.
qualityautoauto, full, light, or off.
triggerimmediateimmediate, scroll, or manual.
speed1Numeric gesture multiplier; use positive values.
scaleResponsive defaultNumeric size multiplier; use positive values.
labelstrue when absentUse labels="false" to match the JavaScript default.
namesBuilt-in poolfalse hides names; a comma-separated list of at least two names replaces the pool.
langDocument languageOverride Swarm Troopers’ text locale for this element.
chatAbsent = falseEnable orchestrator bubbles.
finaleAbsent = truefalse disables the completion celebration.
onceAbsent = falsesession enables session completion storage.
html
<swarmtroopers-overlay
  root="main" auto inspect tokens
  controls="bottom-right" labels="false"
  names="Ada, Mia, Iris" lang="en"
></swarmtroopers-overlay>

Boolean attributes are on when present unless their string value is exactly "false". For example, chat="0" still enables chat. A single custom name such as names="Ada" currently uses the built-in name pool; JavaScript’s names: ['Ada'] supports a one-name pool.

##Access the instance

javascript
const element = document.createElement('swarmtroopers-overlay');
element.setAttribute('root', 'main');
element.setAttribute('auto', '');
element.setAttribute('trigger', 'manual');
element.addEventListener('swarmtroopers-ready', (event) => {
  const swarmtroopers = event.detail;
  swarmtroopers.on('done', (stats) => console.log(stats));
  swarmtroopers.start();
});
document.body.appendChild(element);

// Once connected, element.swarmtroopers is the same instance.

Attach the event listener before connection if you must catch readiness. The event bubbles, and its detail is the same instance exposed as element.swarmtroopers.

##Configuration is read on connection

Attributes are not observed for live changes. Updating speed, root, or lang afterward does not reconfigure the running instance. Use its supported methods for quality or lifecycle changes; use the JavaScript API for object plugins, custom labels, palettes, leadName, patience, or other options without attributes. There is no automatic JavaScript-options-to-attributes mapping.

defineElement(name = 'swarmtroopers-overlay') registers the element under its default tag. A constructor can only be registered under one name, so calling it with another name after the default registration throws.