lumintra

lumintra is a React + WebGL material for tactile refractive glass surfaces. It provides one shared scene renderer, shape surfaces, contact light, frosted and frozen scattering, and interruptible gesture physics.

This is an independent web implementation. It does not use Apple's system renderer, take arbitrary DOM snapshots, or produce physical EDR output. Interaction highlights are SDR light blooms tuned to feel bright without turning the material into a generic glow.

Install

npm install lumintra

Import the structural styles once:

import 'lumintra/styles.css';

Basic Use

import {
  GlassScene,
  LiquidGlass,
  interactionDefaults,
  materialDefaults,
  type InteractionSettings,
  type MaterialSettings,
} from 'lumintra';
import 'lumintra/styles.css';

const material: MaterialSettings = {
  ...materialDefaults,
  frost: 0.62,
  frostStyle: 'frozen',
  lightAngle: 230,
};

const interaction: InteractionSettings = {
  ...interactionDefaults,
  strength: 1.15,
  pressRotation: true,
  dragRotation: false,
};

export function Demo() {
  return (
    <div style={{ width: 640, height: 420 }}>
      <GlassScene
        background={{ type: 'grid', label: 'Grid' }}
        settings={material}
        reduced={false}
      >
        {({ width, height }) => (
          <LiquidGlass
            id="toolbar"
            x={width / 2}
            y={height / 2}
            width={320}
            height={92}
            label="Liquid Glass toolbar"
            shape="capsule"
            interactionMode="elastic"
            interaction={interaction}
          >
            <strong>Прибой</strong>
          </LiquidGlass>
        )}
      </GlassScene>
    </div>
  );
}

Exports

• GlassScene owns the backdrop, WebGL renderer, adaptation, and shared lighting pass.
• LiquidGlass places a capsule, rounded-rect, or ellipse surface inside a scene.
• useMediaPreference reads media queries for reduced motion, contrast, or transparency preferences.
• GlassRenderer is the low-level renderer for advanced integrations.
• materialDefaults, interactionDefaults, resolveMaterial, and resolveInteraction provide safe defaults and bounds.
• SceneProps and SurfaceProps describe the React component contracts.

Layout Contract

GlassScene fills its parent, so the parent must have an explicit positive width and height. Each LiquidGlass surface also needs positive width and height values. A scene renders up to eight glass surfaces in one shared pass.

Backgrounds

Backdrops are explicit: use a URL string, an image object, a grid object, or a canvas source.

type Background =
  | string
  | { type: 'image'; src: string; label?: string; crossOrigin?: 'anonymous' | 'use-credentials' }
  | { type: 'grid'; label?: string }
  | { type: 'canvas'; source: HTMLCanvasElement; revision?: number };

Cross-origin image URLs need CORS headers if the renderer must sample pixels for adaptive foreground color. Canvas backgrounds can pass a changing revision value when the source content changes.

Interaction

Use interactionMode="drag" for movable surfaces, interactionMode="elastic" for stationary controls that stretch while held, and interactionMode="static" for passive glass. Per-surface interaction accepts a partial InteractionSettings, so one shape can use stronger press depth, another can disable press or drag rotation, and a third can behave like a quiet label. draggable remains as a compatibility shortcut for drag behavior; prefer interactionMode for new code.

Material settings are scene-wide because all surfaces share one optical pass. Surface settings describe the shape and gesture response:

<LiquidGlass
  id="confirm"
  x={180}
  y={120}
  width={220}
  height={72}
  label="Confirm"
  shape="rounded-rect"
  interactionMode="elastic"
  interaction={{ strength: 0.9, pressRotation: false }}
/>

Parameters

resolveMaterial and resolveInteraction clamp numeric values to the supported ranges below. Start from the defaults and override only the values that belong to your scene or surface.

| Material setting | Default | Range | Notes | | --- | ---: | ---: | --- | | refraction | 1.2 | 0...3 | Optical bend strength. | | frost | 0.55 | 0...1 | Amount of scattering. | | frostStyle | frozen | matte or frozen | Frozen adds fixed microstructure. | | edgeFrost | 1 | 0...1 | How much frost reaches the rim. | | merge | 32 | 0.01...80 | Shared-surface union radius. | | tint | 0 | 0...1 | Subtle blue material tint. | | solid | false | boolean | Accessible opaque fallback mode. | | dark | false | boolean | Forces dark material foreground. | | variant | regular | regular or clear | Regular adapts; Clear stays more transparent. | | illumination | 1 | 0...2 | Press light exposure. | | lightAngle | 235 | normalized degrees | 0 right, 90 bottom, 180 left, 270 top. | | lightElevation | 35 | 0...90 | Height of the main light above the screen. | | lightIntensity | 1 | 0...2 | Main rim-light intensity. | | followPointer | true | boolean | Lets hover/contact steer part of the light. |

| Interaction setting | Default | Range | Notes | | --- | ---: | ---: | --- | | strength | 1 | 0...2 | Overall press and gesture amplitude. | | pressRotation | true | boolean | Allows tilt during press. | | dragRotation | true | boolean | Allows tilt during drag. | | maxRotation | 4 | 0...12 | Rotation cap in degrees. | | elasticity | 1 | 0...2 | Stretch amount for drag or elastic hold. | | response | 0.4 | 0.15...1 | Spring response time. | | damping | 0.65 | 0.35...1 | Spring damping. |

Package Notes

The package ships ESM JavaScript, TypeScript declarations, and a separate CSS export. Demo copy, sample photos, and application layout styles are intentionally excluded. The material is MIT licensed and supports React 18.3+ and React 19.

Rendering and accessibility

lumintra takes an explicit image, grid, or canvas backdrop; it does not capture arbitrary DOM behind a surface. The WebGL renderer wakes only while a material state is changing. When WebGL is unavailable, the interaction and accessible DOM controls remain available through a CSS fallback.

Use reduced, solid, and dark to follow or apply your product's accessibility policy. The interaction light is an SDR visual treatment, not hardware HDR/EDR output.