The <perlin-noise> element

A renderer-only custom element: no controls, one canvas in a shadow root. How to use it on a page: Embed in a web page.

Scripts

Four plain scripts, loaded in this order, or the single bundle that holds them:

File	Defines
perlin.js	window.MTPerlin — the maths and the worker source
perlin-presets.js	window.MTPerlinPresets — gradients, cosine palettes, built-in presets, resolveParams
perlin-engine.js	window.PerlinEngine — the render engine
perlin-element.js	the <perlin-noise> custom element
dist/perlin-noise.js	all four concatenated (generated by scripts/build-standalone.js)

No ES modules, no build, no dependencies. perlin-gl.js (the GPU renderer) is not part of the bundle; the element draws on the CPU.

Attributes

Attribute	Effect
preset="name"	A built-in preset. Works under file://.
src="file.json"	A preset saved from the studio (format). Needs HTTP(S); fetch is blocked under file://. On failure the element falls back to the default preset and logs a console warning.
autoplay	Start animating once connected (not under reduced motion, not while off-screen).
static	Render a single still frame and do not animate.
max-resolution="N"	Cap on the longest render edge in pixels. Default 1280.

Properties and methods

Member	Meaning
el.params	Get/set the full params object. Setting it wins over src and preset. Gradient and cosine names are expanded.
el.play() / el.pause()	Start or stop the animation.
el.playing	Boolean, whether it is animating now.

Precedence (high to low): params property, src JSON, preset attribute, the default preset.

Behaviour

• Sizing. The element is display: block and fills its container. It renders at the displayed size × devicePixelRatio, capped at max-resolution on the longest edge, and the canvas is scaled by CSS to fill the host.
• Same look at any size. The preset's width and height act as a reference composition: the element scales scaleX and scaleY so features track the composition, not the pixel count.
• Reduced motion. Under prefers-reduced-motion: reduce it never autoplays and draws one still frame; toggling the OS setting while the page is open pauses or resumes.
• Off-screen. It pauses when scrolled fully out of view and resumes when visible again.
• One worker per element. Many instances start many workers.

What a preset may contain

Everything in the preset format works on the element, including the cosine colour mode, the cellular noise types and relief lighting, because they are part of the CPU path the element uses.