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:
import 'swarmtroopers/element';<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
| Attribute | Value / default | Effect |
|---|---|---|
root | Selector; body if absent | Target content root. |
selector | [data-swarmtroopers] | Annotation selector. |
auto | Absent = false | Automatic scanning when present and not "false". |
inspect | Absent = false | Enable finished-element inspection. |
tokens | Absent = false | Install the built-in tokens plugin. |
controls | Absent = no controls | Enable controls; an optional corner value sets position. |
quality | auto | auto, full, light, or off. |
trigger | immediate | immediate, scroll, or manual. |
speed | 1 | Numeric gesture multiplier; use positive values. |
scale | Responsive default | Numeric size multiplier; use positive values. |
labels | true when absent | Use labels="false" to match the JavaScript default. |
names | Built-in pool | false hides names; a comma-separated list of at least two names replaces the pool. |
lang | Document language | Override Swarm Troopers’ text locale for this element. |
chat | Absent = false | Enable orchestrator bubbles. |
finale | Absent = true | false disables the completion celebration. |
once | Absent = false | session enables session completion storage. |
<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
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.