{"_id":"@aberhamm/liquid-glass-react","_rev":"3-0052d612af8aba06d6bd3955d5f5f0e7","name":"@aberhamm/liquid-glass-react","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@aberhamm/liquid-glass-react","version":"0.2.0","keywords":["react","liquid-glass","glassmorphism","backdrop-filter","svg-filter","displacement-map","glass","ui","components","refraction"],"author":{"name":"Matthew Aberham"},"license":"MIT","_id":"@aberhamm/liquid-glass-react@0.2.0","maintainers":[{"name":"aberhamm","email":"matthew.aberham@gmail.com"}],"homepage":"https://github.com/aberhamm/liquid-glass-react#readme","bugs":{"url":"https://github.com/aberhamm/liquid-glass-react/issues"},"dist":{"shasum":"66b51dd886eaab9aede8dfb0affe8171621c91e0","tarball":"https://registry.npmjs.org/@aberhamm/liquid-glass-react/-/liquid-glass-react-0.2.0.tgz","fileCount":16,"integrity":"sha512-V4OWRucDKXkdFuQl942IaQofs4/INAVRp/FRX1rZhwmqc+vh9OarG6MSAkEGaA31C/1WI4IPj1oi4hpSYKFXXg==","signatures":[{"sig":"MEYCIQCP1J3tmCqR0XvNwD2uST2h/abJRi4lEGQFShu0PEtjxgIhANEeox5faokiXatCbX9GaUSuYCBlOdKjacnadU7hJ12d","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":279085},"main":"./dist/index.cjs","pnpm":{"onlyBuiltDependencies":["@biomejs/biome","esbuild"]},"type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"},"react-native":{"types":"./dist/native/index.native.d.ts","default":"./dist/native/index.native.js"}},"./styles.css":"./dist/liquid-glass-react.css"},"gitHead":"9f620c15c2602e5d1b3775d6e8f0bc2418604282","scripts":{"e2e":"pnpm build-storybook && playwright test","attw":"attw --pack . --exclude-entrypoints ./styles.css","lint":"biome check .","test":"vitest run","build":"vite build && pnpm build:native","e2e:ui":"pnpm build-storybook && playwright test --ui","format":"biome format --write .","storybook":"storybook dev -p 6006 --no-open","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:watch":"vitest","test:native":"vitest run --config vitest.native.config.ts","verify:expo":"node scripts/verify-native-resolution.mjs && vitest run --config vitest.native.config.ts","build:native":"tsc -p tsconfig.native.build.json","prepublishOnly":"pnpm lint && pnpm typecheck && pnpm test && pnpm build","build-storybook":"storybook build","typecheck:native":"tsc -p tsconfig.native.json --noEmit"},"_npmUser":{"name":"aberhamm","email":"matthew.aberham@gmail.com"},"repository":{"url":"git+https://github.com/aberhamm/liquid-glass-react.git","type":"git"},"_npmVersion":"11.13.0","description":"An independent React reimplementation of a liquid-glass UI component library.","directories":{},"sideEffects":["**/*.css"],"_nodeVersion":"24.16.0","react-native":"./dist/native/index.native.js","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.3","devDependencies":{"vite":"^6.0.7","jsdom":"^25.0.1","react":"^18.3.1","vitest":"^2.1.8","expo-blur":"^56.0.3","react-dom":"^18.3.1","storybook":"^8.6.18","typescript":"^5.7.3","http-server":"^14.1.1","@types/react":"^18.3.18","react-native":"^0.83.10","@biomejs/biome":"^1.9.4","vite-plugin-dts":"^4.4.0","@playwright/test":"^1.61.0","@storybook/react":"^8.6.18","@types/react-dom":"^18.3.5","react-test-renderer":"^18.3.1","@testing-library/dom":"^10.4.0","expo-linear-gradient":"^56.0.4","@arethetypeswrong/cli":"^0.18.3","@storybook/react-vite":"^8.6.18","@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.3","@storybook/addon-essentials":"^8.6.14","@testing-library/react-native":"^14.0.1"},"peerDependencies":{"react":">=18","expo-blur":">=13","react-dom":">=18","react-native":">=0.74","expo-linear-gradient":">=13"},"peerDependenciesMeta":{"expo-blur":{"optional":true},"react-native":{"optional":true},"expo-linear-gradient":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/liquid-glass-react_0.2.0_1783319823204_0.9438675645527017","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@aberhamm/liquid-glass-react","version":"0.2.1","keywords":["react","liquid-glass","glassmorphism","backdrop-filter","svg-filter","displacement-map","glass","ui","components","refraction"],"author":{"name":"Matthew Aberham"},"license":"MIT","_id":"@aberhamm/liquid-glass-react@0.2.1","maintainers":[{"name":"aberhamm","email":"matthew.aberham@gmail.com"}],"homepage":"https://github.com/aberhamm/liquid-glass-react#readme","bugs":{"url":"https://github.com/aberhamm/liquid-glass-react/issues"},"dist":{"shasum":"d12c30d4afac86d2156e5e19c4c424a6b66835ab","tarball":"https://registry.npmjs.org/@aberhamm/liquid-glass-react/-/liquid-glass-react-0.2.1.tgz","fileCount":16,"integrity":"sha512-vVed3+j1epoY9Ta8TGtfty5ngm70IaFgSqZSPahfoABjC+ph+ZWnnio6rVEI+a7w1hyI3rMb2lMMOlo8PsoA0A==","signatures":[{"sig":"MEYCIQCurZH4AxfXeTHoKRiNsXMzpKUmt6UxH8M9G3sx9q6SnQIhAJvjj+4DwTiIjn5/9MzXpdhNo7STJjp3KWKa4s4AVexE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":279688},"main":"./dist/index.cjs","pnpm":{"onlyBuiltDependencies":["@biomejs/biome","esbuild"]},"type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"},"react-native":{"types":"./dist/native/index.native.d.ts","default":"./dist/native/index.native.js"}},"./styles.css":"./dist/liquid-glass-react.css"},"gitHead":"0e8da46da1da35055d60a027faea8e4cfae91088","scripts":{"e2e":"pnpm build-storybook && playwright test","attw":"attw --pack . --exclude-entrypoints ./styles.css","lint":"biome check .","test":"vitest run","build":"vite build && pnpm build:native","e2e:ui":"pnpm build-storybook && playwright test --ui","format":"biome format --write .","storybook":"storybook dev -p 6006 --no-open","typecheck":"tsc --noEmit","pack:check":"npm pack --dry-run","test:watch":"vitest","test:native":"vitest run --config vitest.native.config.ts","verify:expo":"node scripts/verify-native-resolution.mjs && vitest run --config vitest.native.config.ts","build:native":"tsc -p tsconfig.native.build.json","prepublishOnly":"pnpm lint && pnpm typecheck && pnpm test && pnpm build","build-storybook":"storybook build","typecheck:native":"tsc -p tsconfig.native.json --noEmit"},"_npmUser":{"name":"aberhamm","email":"matthew.aberham@gmail.com"},"repository":{"url":"git+https://github.com/aberhamm/liquid-glass-react.git","type":"git"},"_npmVersion":"11.17.0","description":"An independent React reimplementation of a liquid-glass UI component library.","directories":{},"sideEffects":["**/*.css"],"_nodeVersion":"24.16.0","react-native":"./dist/native/index.native.js","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.3","devDependencies":{"vite":"^6.0.7","jsdom":"^25.0.1","react":"^18.3.1","vitest":"^2.1.8","expo-blur":"^56.0.3","react-dom":"^18.3.1","storybook":"^8.6.18","typescript":"^5.7.3","http-server":"^14.1.1","@types/react":"^18.3.18","react-native":"^0.83.10","@biomejs/biome":"^1.9.4","vite-plugin-dts":"^4.4.0","@playwright/test":"^1.61.0","@storybook/react":"^8.6.18","@types/react-dom":"^18.3.5","react-test-renderer":"^18.3.1","@testing-library/dom":"^10.4.0","expo-linear-gradient":"^56.0.4","@arethetypeswrong/cli":"^0.18.3","@storybook/react-vite":"^8.6.18","@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.3","@storybook/addon-essentials":"^8.6.14","@testing-library/react-native":"^14.0.1"},"peerDependencies":{"react":">=18","expo-blur":">=13","react-dom":">=18","react-native":">=0.74","expo-linear-gradient":">=13"},"peerDependenciesMeta":{"expo-blur":{"optional":true},"react-native":{"optional":true},"expo-linear-gradient":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/liquid-glass-react_0.2.1_1783769526009_0.9586385162275524","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-07-06T06:37:02.990Z","modified":"2026-09-07T12:13:35.545Z","0.2.0":"2026-07-06T06:37:03.344Z","0.2.1":"2026-07-11T11:32:06.222Z"},"bugs":{"url":"https://github.com/aberhamm/liquid-glass-react/issues"},"author":{"name":"Matthew Aberham"},"license":"MIT","homepage":"https://github.com/aberhamm/liquid-glass-react#readme","keywords":["react","liquid-glass","glassmorphism","backdrop-filter","svg-filter","displacement-map","glass","ui","components","refraction"],"repository":{"url":"git+https://github.com/aberhamm/liquid-glass-react.git","type":"git"},"description":"An independent React reimplementation of a liquid-glass UI component library.","maintainers":[{"email":"matthew.aberham@gmail.com","name":"matthewforreal"}],"readme":"# @aberhamm/liquid-glass-react\n\nLiquid-glass UI primitives and batteries-included components for React — a\nfrosted, refractive \"glass\" surface driven by `backdrop-filter` and SVG\ndisplacement filters, with graceful per-engine degradation and zero runtime\ndependencies.\n\n> **Independent reimplementation, not a fork.** This library reimplements the\n> liquid-glass technique popularized by\n> [`rdev/liquid-glass-react`](https://github.com/rdev/liquid-glass-react) and\n> [`shuding/liquid-glass`](https://github.com/shuding/liquid-glass). It shares\n> the *prop surface and intent* — not the code. No source was copied; see\n> [`LICENSE`](./LICENSE) and [`docs/PARITY.md`](./docs/PARITY.md).\n\n- **Frosted glass by default, everywhere** — a portable `backdrop-filter` surface\n (blur + saturate + inset-shadow glass edge + rim + elastic motion) that renders\n the same in Chrome, Safari/WebKit, and Firefox. This is the default look.\n- **Opt-in live-backdrop refraction (`displacement`)** — Chromium-only SVG\n `feDisplacementMap` composited over the live backdrop via `backdrop-filter:\n url()`, plus chromatic aberration. Silently falls back to frosted on\n Firefox/Safari.\n- **Opt-in cross-browser refraction (`refract` / `size` / `center`)** — applies\n the same SVG displacement as an element `filter: url()` on a *copy* of content,\n so a real refractive lens renders in Chrome, Safari **and** Firefox.\n- **Web + Expo/React Native from one install** — the same `` import\n resolves to a native (`expo-blur`) frosted build under Metro. iOS is the quality\n bar; Android is best-effort.\n- **Identical box geometry across every tier** — degrading never shifts layout.\n- **SSR-safe** — conservative capabilities until mount, no hydration mismatch.\n- **Zero runtime dependencies.** React 18+ is a peer dependency; the Expo peer\n deps are optional and web consumers never install them.\n\n---\n\n## Install\n\n```bash\npnpm add @aberhamm/liquid-glass-react\n# or\nnpm install @aberhamm/liquid-glass-react\n# or\nyarn add @aberhamm/liquid-glass-react\n```\n\n`react` and `react-dom` `>=18` are **peer dependencies** — install them in your\napp if you haven't already:\n\n```bash\npnpm add react react-dom\n```\n\n### CSS import\n\nThe **prebuilt components** (`GlassButton`, `GlassCard`,\n`GlassSegmentedControl`) require their stylesheet, imported **once** anywhere in\nyour app (e.g. your root layout or entry):\n\n```ts\nimport '@aberhamm/liquid-glass-react/styles.css';\n```\n\nThe low-level `` **primitive does not need the stylesheet** — it is\nfully self-contained and works without it.\n\n---\n\n## Quick start\n\n### `LiquidGlass` (the primitive)\n\n```tsx\nimport { LiquidGlass } from '@aberhamm/liquid-glass-react';\n\nexport function Badge() {\n return (\n \n Liquid glass\n \n );\n}\n```\n\n### `GlassButton`\n\n```tsx\nimport { GlassButton } from '@aberhamm/liquid-glass-react';\nimport '@aberhamm/liquid-glass-react/styles.css';\n\nexport function Actions() {\n return (\n alert('clicked')}>\n Get started\n \n );\n}\n```\n\n### `GlassCard`\n\n```tsx\nimport { GlassCard } from '@aberhamm/liquid-glass-react';\nimport '@aberhamm/liquid-glass-react/styles.css';\n\nexport function Panel() {\n return (\n \n

Frosted panel

\n

Content stays legible over busy backgrounds.

\n \n );\n}\n```\n\n### `GlassSegmentedControl`\n\n```tsx\nimport { useState } from 'react';\nimport { GlassSegmentedControl } from '@aberhamm/liquid-glass-react';\nimport '@aberhamm/liquid-glass-react/styles.css';\n\nexport function ViewToggle() {\n const [value, setValue] = useState('grid');\n return (\n \n );\n}\n```\n\nThe control is a **native radiogroup** (`
` + visually-hidden\n``), so Arrow/Home/End/Space keyboard navigation and\nscreen-reader semantics work for free. Pass `label` (or `aria-label`) for the\naccessible group name; set `showLabel` to render it visually.\n\n---\n\n## Web usage: frosted default, opt-in refraction\n\nOn the web the glass renders a **portable frosted surface by default** — the same\n`backdrop-filter` blur/saturate look in Chrome, Safari/WebKit, and Firefox. No\nprops are required:\n\n```tsx\nimport { LiquidGlass } from '@aberhamm/liquid-glass-react';\n\n\n Frosted by default — portable across engines\n;\n```\n\nThere are **two independent, opt-in ways** to add real refraction. They compose,\nand both are off by default.\n\n### `displacement` — bend the LIVE page (Chromium only)\n\n`displacement` attaches the SVG `feDisplacementMap` as a `backdrop-filter: url()`,\nso it warps the **live content behind** the glass. This only composites in\nChromium (Chrome, Edge, Brave, Opera); Firefox and Safari/WebKit **silently fall\nback** to the frosted surface.\n\n```tsx\n// Chromium bends the real page behind the glass; other engines stay frosted.\n\n Live-backdrop refraction where supported\n;\n```\n\n> **Upgrading from `0.1.x`?** Refraction used to be the default look. Add\n> `displacement` to restore the old Chromium live-backdrop bend.\n\n### `refract` / `size` / `center` — refract a COPY (cross-browser)\n\nThe cross-browser path applies the same SVG displacement as an **element**\n`filter: url()` on a **copy** of content. Because it filters an element (not the\nbackdrop), a real refractive lens renders in Chrome, Safari **and** Firefox. Two\nmodes:\n\n- **In-place** — pass `size` and/or `center` to refract a copy of the glass's own\n children, with the crisp children on top:\n\n ```tsx\n \n Refracts a copy of its own children — all engines\n ;\n ```\n\n- **Lens over foreign content** — pass `refract={node}` to float a lens over\n content the glass doesn't own; `behind` fills any bleed the copied node doesn't\n cover:\n\n ```tsx\n } behind=\"#0b0b0f\">\n Floats a refractive lens over the poster\n ;\n ```\n\n> **Which bends what?** `displacement` bends the **live page** behind the glass\n> (Chromium only). `refract` / `size` / `center` refract a **copy** of content via\n> an element filter (Chrome, Safari, **and** Firefox). They are distinct and\n> compose. The refracted copy is decorative — `aria-hidden` + `inert` +\n> `pointer-events: none` — so keep the copied subtree **purely presentational**\n> (no `id`s, effects, focusable controls, or data fetching; it mounts twice).\n\n---\n\n## Expo / React Native\n\nThe **same `` import** works in an Expo / React Native app. Metro\nresolves the native build automatically via the package's `react-native` export\ncondition — there is no separate import path:\n\n```tsx\nimport { LiquidGlass } from '@aberhamm/liquid-glass-react';\nimport { Text } from 'react-native';\n\nexport function Badge() {\n return (\n {}}>\n Liquid glass\n \n );\n}\n```\n\nThe native surface renders **frosted glass** — an `expo-blur` `BlurView` with a\ntint and a gradient sheen. It is a genuinely different renderer from the web build,\nso the web-only props are **documented no-ops** on native: `displacement`,\n`refract`, `size`, `center`, `behind`, `saturation`, `variant`, `mode`,\n`aberrationIntensity`, and the pointer/motion props. The native primitive uses\n`onPress` (the web primitive uses `onClick`) and takes `style?: ViewStyle`.\n\n> **iOS is the quality bar; Android is best-effort.** Android uses expo-blur's\n> `experimentalBlurMethod` and degrades gracefully where blur support is limited.\n\n### Optional peer deps\n\nThe Expo target needs two **optional** peer dependencies — `expo-blur` and\n`expo-linear-gradient` — plus `react-native` (and `expo` itself), which your Expo\napp already provides. They are marked `optional` in `peerDependenciesMeta`, so\n**web-only consumers never install them**:\n\n```bash\nnpx expo install expo-blur expo-linear-gradient\n# react-native and expo come from your Expo app itself\n```\n\nThe prebuilt `GlassButton`, `GlassCard`, and `GlassSegmentedControl` are\n**web-only this round** — they are DOM components and are intentionally **not**\npart of the native barrel (`src/index.native.ts`), so they won't resolve in a\nnative bundle. Use the `` primitive on native.\n\n---\n\n## What works where\n\n| Capability | Chrome / Edge | Safari / WebKit | Firefox | Expo (iOS) | Expo (Android) |\n| --- | --- | --- | --- | --- | --- |\n| **Frosted glass** (default) | ✅ | ✅ | ✅ | ✅ | ⚠️ best-effort |\n| **`displacement`** (live-backdrop bend) | ✅ | frosted fallback | frosted fallback | no-op | no-op |\n| **Cross-browser refraction** (`refract` / `size` / `center`) | ✅ | ✅ | ✅ | no-op | no-op |\n| **Prebuilt** `GlassButton` / `GlassCard` / `GlassSegmentedControl` | ✅ | ✅ | ✅ | ❌ web-only | ❌ web-only |\n\nFrosted is the portable default everywhere. `displacement` bends the live page and\nis Chromium-only (frosted fallback elsewhere). The cross-browser `refract` path\nrenders a refractive copy in all three web engines. The prebuilt components are\nweb-only this round.\n\n---\n\n## The `asChild` polymorphism pattern\n\n`GlassButton` and `GlassCard` accept `asChild`. When set, the component renders\n**your** single child element instead of its default tag (`