# glassy-liquid

> Liquid Glass for the web: refraction, specular light, and the iOS 26 controls as Web Components, with React, Vue, and Svelte bindings.

Docs site: https://9und30.github.io/glassy-liquid/

Every control is a custom element (`<glass-button>`, `<glass-switch>`, ...). The React, Vue, and Svelte components wrap those elements and are generated from one binding table, so they have the same names, props, defaults, and events. React callbacks such as `onCheckedChange` are `v-model:checked` in Vue and `bind:checked` in Svelte. Chromium refracts the live page behind the glass. Safari, every iOS browser, and Firefox show a frosted fallback unless the glass sits inside a `<glass-scene>` that names its backdrop (an image URL in `src`, or a `glass-backdrop` child).

## Install

```sh
npm install glassy-liquid
```

## CDN

The `glassy-liquid/cdn` export is `dist/glassy-liquid.min.js`. The script registers every element. `src` is any image URL.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/glassy-liquid@0.1/dist/glassy-liquid.min.js"></script>

<glass-scene src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg" style="height: 100vh; background: linear-gradient(160deg, #9bb7c9, #e7eef2)">
  <glass-button variant="prominent">Continue</glass-button>
  <glass-switch checked aria-label="Wi-Fi"></glass-switch>
</glass-scene>
```

## Export map

- `glassy-liquid`: `glass()`, `attachPress`, and the engine
- `glassy-liquid/elements`: registers every custom element
- `glassy-liquid/react`
- `glassy-liquid/vue`
- `glassy-liquid/svelte`
- `glassy-liquid/svelte/actions`
- `glassy-liquid/components/*`: one module per component
- `glassy-liquid/scene`: the scene element on its own
- `glassy-liquid/cdn`: the minified bundle
- `glassy-liquid/package.json`: package metadata, not a runtime entry

## Scene image

`src` on `glass-scene` accepts any image URL. The URL below is a public CC0 photograph, so the example works when pasted. The scene also paints `linear-gradient(160deg, #9bb7c9, #e7eef2)` when the image fails, and it hides the broken-image icon.

https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg

## Web Components

With a bundler such as Vite. Without a build step, use the CDN script above: a bare `import "glassy-liquid/elements"` only resolves through a bundler or an import map.

```html
<script type="module">
  import "glassy-liquid/elements";
</script>

<glass-scene src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg" style="height: 100vh; background: linear-gradient(160deg, #9bb7c9, #e7eef2)">
  <glass-button variant="prominent">Continue</glass-button>
  <glass-switch checked aria-label="Wi-Fi"></glass-switch>
</glass-scene>
```

## React

```tsx
"use client";

import { useState } from "react";
import { GlassScene, GlassButton, GlassSwitch } from "glassy-liquid/react";

export function Welcome() {
  const [on, setOn] = useState(true);
  return (
    <GlassScene src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg" style={{ height: "100vh", background: "linear-gradient(160deg, #9bb7c9, #e7eef2)" }}>
      <GlassButton variant="prominent">Continue</GlassButton>
      <GlassSwitch checked={on} onCheckedChange={setOn} aria-label="Wi-Fi" />
    </GlassScene>
  );
}
```

## Vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { GlassScene, GlassButton, GlassSwitch } from "glassy-liquid/vue";

const on = ref(true);
</script>

<template>
  <GlassScene src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg" style="height: 100vh; background: linear-gradient(160deg, #9bb7c9, #e7eef2)">
    <GlassButton variant="prominent">Continue</GlassButton>
    <GlassSwitch v-model:checked="on" aria-label="Wi-Fi" />
  </GlassScene>
</template>
```

## Svelte

```svelte
<script>
  import { GlassScene, GlassButton, GlassSwitch } from "glassy-liquid/svelte";
  let on = true;
</script>

<GlassScene src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg/960px-Iceberg_reflection_in_J%C3%B6kuls%C3%A1rl%C3%B3n_%28Unsplash%29.jpg" style="height: 100vh; background: linear-gradient(160deg, #9bb7c9, #e7eef2)">
  <GlassButton variant="prominent">Continue</GlassButton>
  <GlassSwitch bind:checked={on} aria-label="Wi-Fi" />
</GlassScene>
```

## Next.js and server rendering

The React entry (`glassy-liquid/react`) is a Client Component: the file starts with `"use client"`. In the Next.js App Router, import the components from a Client Component.

The React, Vue, and Svelte bindings render `defer-hydration` on each element and remove it after hydration. While the attribute is present the element stays inert, so server markup matches the hydrated tree.

Every entry point is safe to import on the server. Custom elements register only in the browser, where `customElements` exists, so importing `glassy-liquid`, `glassy-liquid/elements`, or a component module from code the server evaluates does not throw. `glass()`, `useGlass()`, and `attachPress()` touch the DOM, so call them in an effect or in `onMount`, as the playground snippets do.

## Docs

- [llms-full.txt](https://9und30.github.io/glassy-liquid/llms-full.txt): this file plus the API reference, theming, and every component in every framework
- [Home](https://9und30.github.io/glassy-liquid/): what the library does and the live hero
- [Components](https://9und30.github.io/glassy-liquid/components.html): every component with Web Components, React, Vue, and Svelte code
- [Playground](https://9und30.github.io/glassy-liquid/playground.html): tune glass options and copy the snippet
- [Getting started](https://9und30.github.io/glassy-liquid/getting-started.html): install, frameworks, SSR, and your own element
- [Theming](https://9und30.github.io/glassy-liquid/theming.html): CSS custom properties and shadow parts
- [Accessibility](https://9und30.github.io/glassy-liquid/accessibility.html): roles, keyboard, and reduced motion or transparency
- [Browser support](https://9und30.github.io/glassy-liquid/browser-support.html): which renderer runs in which browser

## Optional

- [README](https://github.com/9und30/glassy-liquid#readme): the full guide, FAQ, and migration notes
- [Changelog](https://github.com/9und30/glassy-liquid/blob/main/CHANGELOG.md)
- [Issues](https://github.com/9und30/glassy-liquid/issues/new/choose): bug reports and feature requests. Pull requests are not accepted for now