Handle Pattern & Lifecycle

All Liquid Glass components follow the "Handle Pattern." When you initialize a component, the factory function returns a handle object rather than a raw DOM element.

What is a Handle?

A handle is a controller for the component. It provides a clean API to interact with the component's state, subscribe to events, and manage its lifecycle.

Common members found on most handles:

• .element: The root DOM element of the component.
• .on() / .off() / .once(): Methods for event subscription.
• .destroy(): A cleanup method that tears down the component.

Component Lifecycle

1. Initialization

When a component is created, it:

• Generates a unique SVG filter ID.
• Computes displacement and specular maps.
• Injects required SVG elements into the DOM.
• Sets up event listeners and physics loops.

2. Updates

Components can be updated at runtime. For example, a button might update its label, or a slider its value. Many components also automatically refresh their maps if the element is resized (using ResizeObserver where available).

3. Destruction

To prevent memory leaks and unnecessary CPU usage, always call .destroy() when a component is no longer needed (e.g., when a page changes or a UI element is unmounted in a framework like React).

Calling .destroy() will:

• Remove all generated SVG filters.
• Cancel any active animation frames.
• Remove all internal event listeners.
• Restore the original element's state (if applicable).

const handle = createLiquidButton('#btn');

// ... later
handle.destroy();