docs / guides / controls
Quality and controls
Respect reader preferences and expose a clear Full, Light, Off choice.
##Add the built-in controls
import { create, controls } from 'swarmtroopers';
const swarmtroopers = create({ root: 'main', auto: true });
const panel = controls(swarmtroopers, {
position: 'bottom-right',
labels: { title: 'Swarm Troopers', full: 'Full', light: 'Light', off: 'Off' },
});The helper returns an HTMLElement with three pressed-state buttons. It reads the host theme, synchronizes when quality changes, and registers the panel with swarmtroopers.own(), so destroy() removes it.
| ControlsOptions field | Default | Meaning |
|---|---|---|
position | bottom-left | bottom-left, bottom-right, top-left, or top-right. |
labels | Build / Full / Light / Off | Partial overrides of title, full, light, and off. Labels are not automatically translated. |
container | document.body | DOM parent for the panel. Its built-in positioning remains fixed. |
The canvas zIndex option does not change the controls’ CSS stacking level, which is 2147483001. Adapt host CSS if your application requires a different control placement.
##Initial quality resolution
- A valid saved
full,light, oroffvalue understorageKey + ':quality'wins. - Without that preference,
prefers-reduced-motion: reduceselects Off. - Then an explicit quality other than Auto is used.
- Auto selects Light for data-saving connections, four or fewer reported CPU cores, or four or fewer GB of reported device memory. Otherwise it selects Full.
Viewport width alone does not choose Light. Narrow screens separately use smaller pointers and shorter patience. Later system motion changes are resolved the same way while the page is open, when there is no saved manual choice. Explicit reader choices retain precedence.
| Budget | Workers | Canvas density | Result |
|---|---|---|---|
| Full | 6 by default, plus orchestrator | Device pixel ratio capped at 1.5 | The complete build and inspection experience. |
| Light | At most 3, plus orchestrator | Capped at 1 | Fewer workers and faster gestures. |
| Off | No build overlay | No canvas | The existing page is immediately available. |
##Changing quality
swarmtroopers.setQuality('light');
swarmtroopers.setQuality('off'); // Completes pending work and removes the canvas.
swarmtroopers.setQuality('full'); // Does not replay content already completed.The choice persists across reloads when localStorage is available. If storage is blocked, the page still works but the choice is not remembered. Do not continually overwrite a reader’s choice during navigation.
##Session scope and replay
once: 'session' saves completion under storageKey + ':seen'. It is not automatically keyed by URL. Use a page-specific prefix when different pages should each build once; this also gives each prefix its own quality preference.
const swarmtroopers = create({
root: 'main', auto: true,
once: 'session',
storageKey: 'swarmtroopers:portfolio',
});For a Replay button, destroy the previous instance and create another with once: false. Keep your chosen configuration in application code rather than accessing internal settings.