liqbg

A lightweight WebGL liquid background library for any HTMLCanvasElement or container element.

• Custom animated liquid visuals.
• Mobile-first adaptive DPR strategy.

Install

npm i liqbg

Usage (TypeScript)

import { LiqBg } from 'liqbg';

const bg = new LiqBg({
  container: document.getElementById('app') as HTMLElement,
  core: {
    autoResize: true,
    autoStart: true,
    clearColor: '#000000',
  },
  colors: {
    color1: '#000000',
    color2: '#0048ff',
    color3: '#0088ff',
    color4: '#ffffff',
  },
  flow: {
    speed: 0.1148,
    angle: 1.08699,
    foldFrequency: 1.865,
    warpAmount: 4,
    noiseScale: 0.714,
    connections: 0.8715,
  },
  lighting: {
    depth: 0.04,
    shadowWidth: 0.01,
    lightX: 0.968,
    lightY: -0.36,
  },
});

Methods

bg.start();
bg.stop();
bg.resize();
bg.setOptions({ flow: { speed: 0.15 } });
bg.getSettings();
bg.destroy();

Exports

• LiqBg
• LIQBG_CONTROL_DEFINITIONS
• Types: LiqBgOptions, LiqBgPreset, LiqBgControlDefinition, LiqBgCoreOptions, LiqBgColorOptions, LiqBgFlowOptions, LiqBgLightingOptions

Options

Top-level options

| Option | Type | Default | Description | |:------------|:--------------------------------|:--------------|:-------------------------------------------------| | canvas | HTMLCanvasElement | auto-created | Target canvas for rendering. | | container | HTMLElement | parent/body | Element used for sizing and resize tracking. | | core | LiqBgCoreOptions | {} | Runtime options (autostart, resize, DPR limits). | | colors | Partial<LiqBgColorOptions> | {} | Grouped color overrides (color1..color4). | | flow | Partial<LiqBgFlowOptions> | {} | Grouped motion overrides. | | lighting | Partial<LiqBgLightingOptions> | {} | Grouped lighting overrides. |

core options

| Option | Type | Default | Description | |:------------------------|:-------------------------|:--------------|:----------------------------------------------------| | autoResize | boolean | true | Automatically track container size changes. | | autoStart | boolean | true | Start animation loop automatically after init. | | maxPixelRatio | number | 2 | DPR cap for fine-pointer devices. | | clearColor | string | '#000000' | WebGL clear color. | | maxCanvasAreaPxFine | number | 1400 * 1400 | Max internal canvas area on fine-pointer devices. | | maxCanvasAreaPxCoarse | number | 900 * 900 | Max internal canvas area on coarse-pointer devices. | | mobileMaxPixelRatio | number | 1.5 | DPR cap on coarse-pointer devices. | | dprQuantStep | number | 0.25 | DPR quantization step used by resize/perf logic. |

Adaptive DPR behavior is built in and works automatically.

Visual override options (colors, flow, lighting)

Defaults below match the built-in base settings.

| Option | Type | Default | Group | |:-----------------|:---------|:------------|:-----------| | color1 | string | '#000000' | colors | | color2 | string | '#0048ff' | colors | | color3 | string | '#0088ff' | colors | | color4 | string | '#ffffff' | colors | | speed | number | 0.1148 | flow | | angle | number | 1.08699 | flow | | foldFrequency | number | 1.865 | flow | | warpAmount | number | 4 | flow | | noiseScale | number | 0.714 | flow | | connections | number | 0.8715 | flow | | depth | number | 0.04 | lighting | | shadowWidth | number | 0.01 | lighting | | lightX | number | 0.968 | lighting | | lightY | number | -0.36 | lighting |

Only grouped modern options are supported (core, colors, flow, lighting).

Acknowledgements

This project is based on the visual and shader concept from Organic Background - Three.js by sabosugi, and includes adapted implementation ideas from that source.

The codebase was substantially reworked for production use: the THREE.js runtime was removed, rendering was rewritten to low-level WebGL, and lifecycle plus adaptive DPR behavior were implemented with a mobile-first focus.

License

MIT