React and Vue
Both adapters create one liquiddom instance for a part of your app and observe elements as they mount. They take the same config as LiquidDOM.create(), read once when the provider mounts.
React
npm install liquiddom@alpha @liquiddom/react@alpha
React 18 (19 is in the peer range but untested).
import { LiquidProvider, LiquidElement, useLiquid, useLiquidError } from "@liquiddom/react";
export default function App() {
return (
<LiquidProvider config={{ material: { viscosity: 0.6 } }}>
<Pills />
</LiquidProvider>
);
}
function Pills() {
const liquid = useLiquid(); // the instance, or null
const error = useLiquidError(); // why there is none, or null
return (
<>
<LiquidElement as="button" className="pill" onClick={() => liquid?.shake()}>
Shake
</LiquidElement>
<LiquidElement as="input" drag={false} aria-label="Search" />
{error !== null ? <p role="status">The liquid stopped.</p> : null}
</>
);
}
<LiquidProvider config>creates the instance on mount and destroys it on unmount.<LiquidElement as viscosity recovery drag>rendersas(defaultdiv) and observes it.viscosity,recoveryanddragare element options, read once when the element first attaches; every other prop goes to the DOM element.useLiquidRef(opts?)is the hook behind it: a callback ref for your own element.useLiquid()returns the instance, ornullbefore it is ready, outside a provider and after a stop.useLiquidError()returns the error that left the provider without an instance, ornull.
Vue
npm install liquiddom@alpha @liquiddom/vue@alpha
Vue 3.4 or newer. Install the plugin for the whole app, or wrap a subtree in <LiquidProvider>:
import { createApp } from "vue";
import { LiquidPlugin } from "@liquiddom/vue";
import App from "./App.vue";
createApp(App).use(LiquidPlugin, { material: { viscosity: 0.6 } }).mount("#app");
<script setup lang="ts">
import { LiquidElement, useLiquid, useLiquidError } from "@liquiddom/vue";
const liquid = useLiquid(); // Ref: the instance, or null
const error = useLiquidError(); // Ref: why there is none, or null
</script>
<template>
<LiquidElement as="button" class="pill" @click="liquid?.shake()">Shake</LiquidElement>
<LiquidElement as="input" :drag="false" aria-label="Search" />
<p v-if="error !== null" role="status">The liquid stopped.</p>
</template>
LiquidPlugin(app.use(LiquidPlugin, config)) creates one instance for the app and destroys it onapp.unmount().<LiquidProvider :config>does the same for its subtree.<LiquidElement as viscosity recovery drag>,useLiquidRef(opts?),useLiquid()anduseLiquidError()work as in React; the two hooks return refs.LiquidKeyandLiquidErrorKeyare the injection keys.
When the liquid stops
An instance can stop for good after it started (see Errors). Both adapters handle it the same way:
- The provider (or plugin) destroys the stopped instance at once, so no element stays decorated on a dead canvas.
useLiquid()becomesnullanduseLiquidError()holds the error. Acreate()rejection sets the error too.- There is no automatic retry. Remount the provider to create a new instance, for example with a new
keyin React orv-ifin Vue.
Your own config.onError is still called, after the adapter’s handler. Elements stay usable throughout: a stopped liquid only means no liquid is drawn.