React Flexi Window

A flexible, draggable, and resizable window component for React with WASM-powered refractive glass materials and zero dependencies.

Features

• Draggable: Click and drag to move windows around
• Resizable: Drag edges and corners to resize windows
• Assistive Resize Handles: Large, visible corner handles appear during interaction for enhanced usability
• Boundary Constraints: Optionally confine windows to viewport
• Refractive Materials: Built-in WASM-powered liquid glass material with Snell's Law optics
• SSR Safe: Fully compatible with Next.js and other SSR frameworks
• Customizable Styling: Built-in color themes and effects
• Responsive: Adapts to viewport changes automatically
• Zero Dependencies: No external dependencies except React
• Lightweight: ~14KB gzipped including the WASM engine
• TypeScript Support: Full TypeScript definitions included
• Smart Interactions: Respects interactive elements (buttons, inputs, etc.)
• Performance Optimized: Uses efficient event handling, WASM computation, and 9-slice rendering

Installation

npm install react-flexi-window

Basic Usage

import React from 'react';
import WindowComponent from 'react-flexi-window';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh', position: 'relative' }}>
      <WindowComponent
        w={400}
        h={300}
        x={100}
        y={100}
        windowColor="blue-500/20"
        windowBorderColor="blue-600/50"
        windowBorderRadius="lg"
        windowBorder={1}
        windowShadow="lg"
        boundary={true}
      >
        <div style={{ padding: '20px' }}>
          <h2>My Window</h2>
          <p>This is a draggable and resizable window!</p>
        </div>
      </WindowComponent>
    </div>
  );
}

Material System

The material prop enables advanced visual effects on the window surface. Materials are created using helper functions that return descriptors.

Liquid Glass

Creates a realistic refractive glass effect using a WASM-powered optics engine. The effect bends the background content through the window edges using Snell's Law refraction, and adds specular highlights for depth.

import WindowComponent, { liquidGlass } from 'react-flexi-window';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh', position: 'relative' }}>
      <WindowComponent
        w={400}
        h={300}
        x={100}
        y={100}
        material={liquidGlass(16, 3, 12)}
        boundary={true}
      >
        <div style={{ padding: '20px', color: 'white' }}>
          Content behind glass
        </div>
      </WindowComponent>
    </div>
  );
}

liquidGlass(radius, blur, bezelWidth)

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | radius | number | 12 | Corner radius of the glass. Clamped to 0 minimum. | | blur | number | 4 | Backdrop blur intensity behind the glass. Clamped to 0 minimum. | | bezelWidth | number | 10 | Width of the refractive bezel edge. Clamped to 0 minimum. |

When material is provided, it overrides windowBorderRadius and windowBackgroundBlur with the material's own values.

How It Works

1. A Rust-based WASM module (~6KB) computes displacement and specular maps using ray optics
2. Maps are split into 9-slice parts for scalable SVG filter rendering
3. The SVG backdrop-filter pipeline applies blur, displacement, and specular in one pass
4. All computation runs in useLayoutEffect to avoid visual flash on first paint
5. The WASM binary is inlined as base64 — no network fetch, no external files

Props

Size and Position Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | w | number \| 'auto' \| 'full' | 'auto' | Initial width in pixels, 'auto', or 'full' (100%) | | h | number \| 'auto' \| 'full' | 'auto' | Initial height in pixels, 'auto', or 'full' (100%) | | x | number | 50 | Initial X position | | y | number | 50 | Initial Y position | | minW | number | 1 | Minimum width in pixels | | minH | number | 1 | Minimum height in pixels | | maxW | number \| 'viewport' | Infinity | Maximum width in pixels, or 'viewport' to constrain to browser window | | maxH | number \| 'viewport' | Infinity | Maximum height in pixels, or 'viewport' to constrain to browser window |

Behavior Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | boundary | boolean | false | If true, restricts dragging and position to within the viewport | | overflow | string | 'auto' | CSS overflow property | | overflowX | string | 'auto' | CSS overflow-x property | | overflowY | string | 'auto' | CSS overflow-y property | | zIndex | number | 1 | Z-index value | | material | object | undefined | Material descriptor from liquidGlass() or future material functions |

Styling Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | Additional CSS classes | | windowColor | string | '' | Background color (format: 'colorname-intensity/opacity') | | windowBorderColor | string | '' | Border color | | windowBorderRadius | string | '' | Border radius | | windowBorder | number | 0 | Border width in pixels | | windowShadow | string | '' | Box shadow | | windowBackgroundBlur | string | '' | Backdrop blur filter | | windowBackgroundSaturation | string | '100' | Backdrop saturation |

Color System

The component uses a built-in color system with the following format: colorname-intensity/opacity

Available Colors

• red, blue, green, yellow, purple, pink, indigo, gray, slate, zinc, emerald

Intensities

• 50, 100, 200, 300, 400, 500, 600, 700, 800, 900

Opacity (optional)

• Any number from 0-100 (e.g., /20 for 20% opacity)

Examples

windowColor="blue-500/30"        // Blue with 30% opacity
windowBorderColor="red-600/80"   // Red border with 80% opacity
windowColor="emerald-400"        // Emerald with 100% opacity (default)

Border Radius Options

• none, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl, 8xl, 9xl, 10xl, 11xl, 12xl, full

Shadow Options

• none, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl
• Can include opacity: lg/30 for large shadow with 30% opacity

Blur Options

• none, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl

Examples

Liquid Glass Window

import WindowComponent, { liquidGlass } from 'react-flexi-window';

<WindowComponent
  w={400} h={300} x={100} y={100}
  material={liquidGlass(16, 3, 12)}
  boundary={true}
  windowColor="white/10"
  windowBorder={1}
  windowBorderColor="white/20"
>
  <div style={{ padding: '20px', color: 'white' }}>
    <h3>Glass Window</h3>
    <p>Refractive glass effect with WASM-powered optics.</p>
  </div>
</WindowComponent>

Multiple Windows

<div style={{ width: '100vw', height: '100vh', position: 'relative' }}>
  <WindowComponent
    w={300} h={200} x={50} y={50}
    windowColor="blue-500/30"
    windowBorderRadius="xl"
    windowShadow="xl"
    zIndex={1}
  >
    <div style={{ padding: '15px' }}>
      <h3>Window 1</h3>
    </div>
  </WindowComponent>
  
  <WindowComponent
    w={350} h={250} x={200} y={150}
    windowColor="green-500/25"
    windowBorderRadius="2xl"
    windowShadow="2xl"
    zIndex={2}
  >
    <div style={{ padding: '15px' }}>
      <h3>Window 2</h3>
    </div>
  </WindowComponent>
</div>

Constrained Window

<WindowComponent
  w={400}
  h={300}
  boundary={true}
  maxW="viewport"
  maxH="viewport"
  windowColor="purple-500/20"
  windowBorderColor="purple-600/50"
  windowBorderRadius="lg"
  windowBorder={2}
  windowShadow="lg"
  windowBackgroundBlur="md"
>
  <div style={{ padding: '20px' }}>
    <h2>Constrained Window</h2>
    <p>This window cannot be dragged outside the viewport.</p>
  </div>
</WindowComponent>

TypeScript Support

The component includes full TypeScript definitions:

import WindowComponent, { liquidGlass } from 'react-flexi-window';
import type { WindowComponentProps, LiquidGlassDescriptor } from 'react-flexi-window';

const material: LiquidGlassDescriptor = liquidGlass(16, 3, 12);

Browser Support

• Chrome/Edge 88+
• Firefox 84+
• Safari 14+

Behavior Details

Smart Interaction Handling

• Interactive Elements: The component automatically prevents dragging when clicking on interactive elements like buttons, inputs, textareas, links, and contentEditable elements
• Assistive Resize Handles: During window interaction, large 40x40px corner handles appear to make resizing easier, especially on touch devices
• Viewport Responsiveness: Windows automatically adjust their position and size when the browser window is resized
• Boundary Enforcement: When boundary={true}, windows are constrained both during dragging and when the viewport changes
• Text Selection: Text selection is preserved when not interacting with the window

Material System Architecture

• WASM Engine: Rust-compiled WebAssembly module performs Snell's Law refraction math with no_std, no allocator, zero GC overhead
• Inline Binary: The ~6KB WASM module is base64-inlined — no fetch, no network dependency
• 9-Slice Rendering: Displacement and specular maps are split into scalable 9-slice SVG images
• SSR Safety: All browser APIs (Canvas, WebAssembly) are called inside useLayoutEffect — server render produces clean HTML
• Pre-warming: The WASM module initializes on first import, ready before the component mounts

Performance Optimizations

• Uses useCallback for event handlers to prevent unnecessary re-renders
• Efficient event listener management (adds/removes based on interaction state)
• Minimal DOM updates during dragging and resizing
• WASM computation runs once per parameter change, not per frame

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.