liquidglass

Apple's iOS 27 Liquid Glass for React and React Native

Glass that bends the light behind it, and the iOS controls built from it,
measured against the real thing on the iOS simulator.

Live demo · Web quick start · React Native quick start · Prompt for your AI agent · Performance · FAQ

Web real iOS 27 left, liquidglass right	React Native, iOS Apple's own glass	React Native, Android drawn to iOS's measurements

Use it with an AI agent

Copy this prompt into Claude Code, Cursor, Codex or any coding agent, and replace the last step with what you want built. It has the agent pick the right package for your project and read the liquidglass skill before it writes any code.

Add Apple's iOS 27 Liquid Glass to this app using liquidglass.

1. Before writing any code, install the liquidglass agent skill and read it:
     npx skills add onlymoein/liquidglass
   If you can't run that, read the skill straight from GitHub:
     https://github.com/onlymoein/liquidglass/blob/main/skills/liquidglass/SKILL.md
   Follow it for everything below.

2. Look at this project and pick the matching package:
   - A website or web app (React, Next.js, Vite, Remix):
       npm install @onlymoein/liquidglass
   - A mobile app (React Native or Expo):
       npx expo install @onlymoein/liquidglass-native expo-glass-effect
     It has native code, so rebuild with `npx expo run:ios` or `npx expo run:android`;
     it doesn't run in Expo Go. Read node_modules/@onlymoein/liquidglass-native/README.md,
     and on Android wrap what the glass should show in a <Backdrop>.
   If the project has both, use each package in its own app.

3. Use the library's components (Glass, Button, Switch, Slider, Stepper, SegmentedControl,
   Menu, TabBar, and on the web Toolbar, NavigationBar, Sheet, Alert, Input) instead of
   hand-made blur or "glassmorphism" CSS. Keep to the skill's rules: put glass over
   something colourful, don't nest glass inside glass, don't wrap it in opacity or filter,
   and give icon-only controls an aria-label (accessibilityLabel in React Native).

4. Build this: <describe what you want, for example "replace the bottom navigation with
   a TabBar and the settings toggles with Switch">

5. When you're done, run the app, look at the screens you changed, and tell me what you
   changed and anything that didn't work.

The skill teaches the agent both packages: the components and their props, theming, browser differences, and what to check when glass looks wrong. To install it yourself:

npx skills add onlymoein/liquidglass

It also ships in the web package, at node_modules/@onlymoein/liquidglass/skills/liquidglass/SKILL.md.

Performance

Glass is expensive to draw, so liquidglass does the heavy work where it can't slow your page down. These numbers are from the demo and the bundle, checked on every pull request:

• The lens maps and rims are drawn in a Web Worker, off the page's thread. Glass is frosted at once and picks up its lens a moment later.
• Each piece of glass holds only the maps it's drawn with, and they're freed once nothing uses them.
• Each component brings only its own CSS, the first time it renders.
• Safari uses its native blur, and Firefox's bent copy of a backdrop updates in small slices while the page is idle, so neither holds the page up.
• Content Security Policy: allow worker-src blob: and img-src blob: data:.

The checks are npm run size, npm run perf:lighthouse and npm run perf:frames. The last one scrolls the demo, grows and restyles Firefox's copied backdrop, and drags the window narrower, failing if the page is held up or lenses pile up.

Why liquidglass

• One API for web and mobile. Button, Switch, Slider, Menu, TabBar and the rest have the same names and props in React and React Native.
• Measured, not eyeballed. The repo runs real iOS controls and this library side by side on the simulator and measures the difference. In Chrome, glass colour is within 2 levels out of 255 of iOS.
• The real thing on iPhone. In React Native on iOS, the components are Apple's own UIKit glass and controls. On Android, the package draws the glass itself, to the same measurements.
• Moves like iOS. Presses, menus, sheets and the tab bar's lens are on springs fitted to recordings of iOS 27.
• Fast. 99 on Lighthouse mobile, nothing holding up the page, about 12 kB per Button. See Performance.
• Accessible. Keyboard and screen-reader support throughout. Glass turns fully tinted when the system is set to reduce transparency or increase contrast.
• Ready for AI coding agents. A ready-made prompt and an agent skill teach Claude Code, Cursor or Codex the whole library.

Quick start

React for the web

npm install @onlymoein/liquidglass

import { Button, Glass, Switch } from "@onlymoein/liquidglass";

export function Settings() {
  return (
    <Glass style={{ borderRadius: 28, padding: 20 }}>
      <Switch aria-label="Wi-Fi" defaultChecked />
      <Button variant="filled">Continue</Button>
    </Glass>
  );
}

There's no other setup: each component brings its own CSS the first time it renders. It needs React 18 or later. Put glass over a photo, a gradient or content that scrolls, since glass shows what's behind it.

React Native and Expo

npx expo install @onlymoein/liquidglass-native expo-glass-effect
npx expo run:ios   # or run:android

import { Button, Glass, Slider, Switch } from "@onlymoein/liquidglass-native";

export function Player() {
  return (
    <Glass style={{ padding: 16, borderRadius: 28, gap: 12 }}>
      <Switch defaultChecked />
      <Slider defaultValue={0.5} />
      <Button label="Done" variant="filled" onPress={() => {}} />
    </Glass>
  );
}

It needs Expo SDK 54 or later and a development build; it doesn't run in Expo Go. On Android, wrap what the glass should show in a Backdrop. The full guide is in the React Native README.

Components

Every control can be controlled (value / checked / open with onValueChange / onCheckedChange / onOpenChange) or uncontrolled (defaultValue / defaultChecked / defaultOpen).

import { Button, Toolbar, ToolbarGroup } from "@onlymoein/liquidglass";

<Toolbar aria-label="Notes">
  <ToolbarGroup aria-label="Navigation">
    <Button>Back</Button>
  </ToolbarGroup>
  <ToolbarGroup aria-label="Actions">
    <Button>Share</Button>
    <Button>Edit</Button>
  </ToolbarGroup>
</Toolbar>

import { Button, NavigationBar, ToolbarGroup } from "@onlymoein/liquidglass";

<NavigationBar
  title="Inbox"
  onBack={goBack}
  trailing={
    <ToolbarGroup aria-label="Actions">
      <Button aria-label="Compose" icon={<ComposeIcon />} />
    </ToolbarGroup>
  }
/>

import { Menu } from "@onlymoein/liquidglass";

<Menu
  aria-label="Account"
  label="Account"
  items={[
    { heading: "Appearance" },
    { label: "Light", checked: theme === "light", keepOpen: true, onSelect: () => setTheme("light") },
    { label: "Dark", checked: theme === "dark", keepOpen: true, onSelect: () => setTheme("dark") },
    "separator",
    { label: "Sign out", destructive: true, onSelect: signOut },
  ]}
/>

import { Alert, Sheet } from "@onlymoein/liquidglass";

<Sheet aria-label="Details" open={open} onOpenChange={setOpen}>
  {details}
</Sheet>

<Alert
  open={asking}
  onOpenChange={setAsking}
  title="Delete shipment?"
  message="This can't be undone."
  actions={[{ label: "Cancel", role: "cancel" }, { label: "Delete", role: "destructive", onSelect: remove }]}
/>

import { Button, GlassGroup } from "@onlymoein/liquidglass";

<GlassGroup spacing={20} style={{ gap: 6 }}>
  <Button aria-label="Add" icon={<PlusIcon />} />
  <Button aria-label="Edit" icon={<PencilIcon />} />
</GlassGroup>

:root {
  --lg-transparency: 0.8;
}

Browser support

Only Chromium lets a page bend what's behind an element. Everywhere else the glass looks the same, but its edge doesn't bend. In Firefox, add data-liquidglass-backdrop to a wallpaper or hero image behind the glass, and the glass bends a copy of it. Keep it to a small area, since everything inside it is copied for every piece of glass over it.

<img data-liquidglass-backdrop src="/wallpaper.jpg" alt="" />

FAQ

Does it work in Next.js? Yes. The components are client components, so you can import them from server component files. Their styles are added on the client.

Why doesn't the edge bend in Safari? Safari doesn't let a web page filter what's behind an element. The glass has the same colour, blur and rim there; only the bend is missing.

My glass is invisible or plain grey. Glass needs something colourful behind it. Also check its ancestors: one with opacity below 1, filter, mask or backdrop-filter limits the glass to what's inside that ancestor. Glass nested in other glass has the same problem.

Does the React Native package work in Expo Go? No. It has native code, so it needs a development build (npx expo run:ios) or EAS Build.

What about Android? Android has no Liquid Glass, so the package draws its own to iOS's measurements. It bends from Android 13, and is blurred and toned without the bend before that. See Android.

I used glisse. liquidglass started as a fork of glisse by Kelvin Zhang, and the components and props are the same. Change your imports, and rename data-glisse-backdrop to data-liquidglass-backdrop. If you set --lg-glass, set --lg-glass-tinted and --lg-transparency instead.

License

MIT. Copyright Kelvin Zhang and Moein Saharkhiz.

liquidglass is an independent project. It isn't affiliated with or endorsed by Apple. Apple, iOS and Liquid Glass are trademarks of Apple Inc.