Troubleshooting

Diagnose installation, styling, hydration, and glass-rendering problems.

Start by confirming the application uses React 19, imports the aggregate stylesheet once, and renders a minimal component without application wrappers:

import { Button } from "@liquidify/react"
import "@liquidify/react/styles.css"

export function CheckLiquidify() {
return <Button onPress={() => console.log("ok")}>Check</Button>
}

If this works, restore providers and layout wrappers one at a time until the conflicting boundary is visible.

The component has no Liquidify styling

Confirm @liquidify/react/styles.css is imported from an application root or global stylesheet entry.
Do not import package source files or internal CSS paths.
Check that the bundler is not excluding package CSS.
If using only @liquidify/glass, import @liquidify/glass/glass.css instead.

Glass blur or refraction is missing

Glass needs visible content behind the surface. Test over a textured or contrasting backdrop, not a flat color that makes blur impossible to see.

The complete SVG filter path is progressive. Safari and Firefox receive frost and static specular treatment without the Blink refraction path. Check the supported floors in Browser support before treating that difference as a defect.

Also inspect ancestor styles for overflow, transforms, opacity, or isolation that create an unexpected clipping or stacking context.

Hydration warnings

Keep controlled values identical between the server render and first client render.
Put event handlers and browser-only state inside a client component.
Do not read window, document, or storage at module scope.
Start overlays closed unless their initial open state is deterministic on both server and client.

See Server rendering for a complete boundary pattern.

Overlays are clipped or hidden

Dialog, sheet, popover, menu, tooltip, and related floating content use portals. If a surface appears under application chrome, remove ad hoc z-index values and check whether the application has created an unrelated stacking context around the portal host.

If focus or dismissal behaves unexpectedly, reproduce with the overlay alone and verify that controlled open state is updated in onOpenChange.

TypeScript rejects a prop

Use the generated component page as the source of truth. Liquidify controls intentionally do not all expose the same axes: a prop such as material, size, tint, or name may be valid for one component and absent from another.

Pin the installed version, then compare it with the version documented by this site. The API is currently experimental and can change between releases.