🍬 <hydra-element>

A DOM-native Web Component for the Hydra visual synthesizer.

Create generative visuals with Hydra in any HTML page.

<script type="module" src="https://cdn.jsdelivr.net/npm/hydra-element"></script>

<hydra-element>osc(10, 0.2, 0.5).out()</hydra-element>

That's it — write Hydra code between the tags and you're live. Each element runs its own engine, so several on one page don't interfere.

Demo

Want to poke around? Open the CodePen demo, or run the local playground (pnpm dev) for a sketch gallery.

Install

<script type="module" src="https://cdn.jsdelivr.net/npm/hydra-element"></script>

or

npm install hydra-element   # or pnpm / yarn

import 'hydra-element'

The class is also exported if you need it directly:

import { HydraElement } from 'hydra-element'

Write code

The full Hydra DSL works between the tags (osc(), noise(), solid(), setFunction(), sources s0–s3, outputs o0–o3, time, bpm, speed, mouse) — no synth. prefix needed. await works too, so async sources and loadScript(...) are supported.

<hydra-element>
  osc(30, 0.01, 1)
    .mult(osc(() => 100 * Math.sin(time * 0.1), -0.1, 1).modulate(noise(3, 1)).rotate(0.7))
    .blend(src(s0))
    .posterize([3, 10, 2].fast(0.5).smooth(1))
    .out()
</hydra-element>

Change the scene from JS:

document.querySelector('hydra-element').code = 'osc(20).out()'

Or drive the synth directly once it's ready:

const el = document.querySelector('hydra-element')
const { synth } = await el.ready
synth.s0.initImage('...')
synth.bpm = 120

This is not a sandbox — code runs in your page, so only evaluate code you trust.

Binding values

Feed values from your page into the sketch without touching globalThis. Bound names can also shadow the engine's built-ins (time, width, speed, …):

const el = document.querySelector('hydra-element')
const slider = document.querySelector('#freq')

// static — a pinned value; shadows the engine's own `speed` read
el.bind('speed', 1.5)
// live — a getter re-read on every access: moving the slider updates the scene
el.bindLive('freq', () => Number(slider.value))
// remove it; the engine's own `speed` read applies from then on
el.unbind('speed')

<hydra-element>osc(() => freq, 0.1, speed).out()</hydra-element>
<input id="freq" type="range" min="1" max="120" value="30">

Parameters only re-evaluate per frame when passed as functions: osc(freq, …) pins, osc(() => freq, …) stays live. A sketch can override a binding with a bare assignment; bind/bindLive restores it.

Attributes

| Attribute | Default | What it does | | --- | --- | --- | | width / height | CSS | Canvas backing size in pixels (overrides the CSS size). | | dpr | 2 | Cap for the device-pixel-ratio used by auto-sized canvases. | | precision | default | Shader precision: highp, mediump, lowp. | | sources / outputs | 4 | Number of source/output buffers (0–16). Extra buffers are s4, s5, …. | | audio | false | Enable audio analysis (a.fft, …) — requests microphone access. | | global | false | Keep Hydra globals on window. Use at most one per document. | | loop | true | Whether the element drives its own render loop. |

Auto-sized canvases follow the layout via ResizeObserver, scaled by min(devicePixelRatio, dpr). Changing width/height/dpr resizes in place.

Turn loop off and drive frames yourself with tick:

<hydra-element loop="false"></hydra-element>

const el = document.querySelector('hydra-element')
function frame(now) {
  el.tick(now - last)
  last = now
  requestAnimationFrame(frame)
}

You can toggle loop at runtime too — it starts/stops the loop without recreating the engine.

API

| Member | Type | Description | | --- | --- | --- | | code | get/set | The scene source. Setting it (re)evaluates the sketch. | | ready | get (read-only) | Promise<{ synth }> that resolves once the engine is initialized. | | tick(dt) | method | Manual frame tick (ms) — used when loop="false". | | canvas | get/set | The backing <canvas>. Assign your own to take over rendering. | | synth | get (read-only) | The hydra-synth engine (el.synth.osc, el.synth.s0, …). | | transforms | get/set | Array of custom GLSL functions (setFunction under the hood). | | pb | get/set | An rtc-patch-bay instance for streaming (recreates the engine). | | scope | get | The persistent eval scope — bare assignments, bound values, and _hydra/hydraSynth live here. | | bind(name, value) | method | Binds a static value into the eval scope; wins over live engine-owned reads (time, width, …). | | bindLive(name, fn) | method | Binds a getter re-read on every access (a sketch assignment replaces it). | | unbind(name) | method | Removes a previously bound value or live getter. | | loadScript(url) | method | Loads an extension script, scoped to this element. | | capture() | method | The next rendered frame as a PNG Blob (needs the loop running). | | destroy() | method | Tears the element down in place; also automatic on removal. |

Capturing frames

const el = document.querySelector('hydra-element')
const blob = await el.capture() // PNG of the next rendered frame

Events

Bubbling CustomEvents dispatched on the element:

| Event | Detail | | --- | --- | | hydra-eval | { success, error?, line? } — after each code assignment. | | hydra-ready | { synth } — after every engine (re)initialization. | | hydra-loadscript | { success, url, error? } — after a loadScript(url) call (rethrows on failure). | | hydra-element-resize | { width, height } — when the canvas backing store resizes. |

el.addEventListener('hydra-eval', e => {
  if (!e.detail.success) console.error(e.detail.error)
})

Framework integration

<hydra-element> is a standard Web Component, so it works in any framework that supports them. The key bits are its properties (code, synth, bind, …) and the hydra-eval / hydra-ready events.

React

React 19+ maps matching props to properties and custom events to onHydraEval / onHydraReady:

<hydra-element
  audio="false"
  onHydraEval={e => e.detail.success ? null : console.error(e.detail.error)}
/>

React < 19 has no custom-element prop support — drive the element with a ref (code, bind, addEventListener). Removing the element from the DOM frees its engine automatically, so no manual cleanup is needed.

Vue

Vue 3 binds props as properties and listens to events with @hydra-eval; set isCustomElement to avoid the "failed to resolve component" warning:

// vite.config.js
vue({ template: { compilerOptions: { isCustomElement: tag => tag === 'hydra-element' } } })

Other frameworks

Solid, Svelte, Angular and Preact render it natively — bind values via the element's properties and attach the events with the framework's regular syntax. Removing the element from the DOM frees its engine automatically.

Styling with ::part

The internal canvas and the audio analyzer are exposed as CSS parts:

hydra-element::part(canvas) {
  border-radius: 0.5rem;
}

/* hide the audio analyzer overlay */
hydra-element::part(analyzer) {
  display: none;
}

Extensions

Load any Hydra extension with loadScript — no global attribute needed. The script is fetched and evaluated inside the element's scope:

<hydra-element>
  await loadScript("https://cdn.jsdelivr.net/gh/geikha/hyper-hydra@latest/hydra-arithmetics.js")

  osc(10,.1,2)
    .mod(gradient().asin().cos())
    .step(noise(2).unipolar().div(o0))
    .blend(o0,.2)
    .out()
</hydra-element>

Note — extensions built for the classic single-global editor read window._hydra, window.hydraSynth, window.update, etc. Across several isolated elements the bridge may resolve to the wrong engine, and anything global by nature (UI appended to document.body, APIs on window) can collide.

Evaluation context

Evaluation is provided by hydra-context.

Notes and limitations

• ~16 WebGL contexts per browser — ~12+ elements on one page may hit it.
• hydra-synth itself is only tested with 4 outputs; raise outputs with caution.
• No p5 wrapper — the classic editor ships a global p5; here load it yourself and bind it in.

Acknowledgements

• Olivia Jack for creating Hydra 🌈
• The Hydra community for the extensions and ecosystem that surround it 🧩

Development

See CONTRIBUTING.md and ARCHITECTURE.md.

License

AGPL-3.0-or-later.