# mri-fivem-liquid-glass

> Real liquid glass and game blur for FiveM NUI: blurs and refracts the live GTA V frame behind your HTML elements, where CSS backdrop-filter cannot see the game.

Install with `npm i mri-fivem-liquid-glass`, call `startGameGlass()` once, mark elements with `data-glass` or `data-glass="liquid"`. Keep html, body and the UI root transparent, put the UI root above the glass canvas (position: relative; z-index: 1) and never use backdrop-filter on glass elements.

## Recipe: replace backdrop-filter in a FiveM NUI

Follow these steps in order when asked to replace backdrop-filter (or add glass) in a FiveM resource. The library only sees the game frame, so it is for glass whose backdrop is the game.

1. Find the NUI: the `ui_page` in `fxmanifest.lua`, and its source if it is built (Vite, React, Vue, Svelte) or plain HTML.
2. Install: with a bundler run `npm i mri-fivem-liquid-glass`; for plain HTML copy `node_modules/mri-fivem-liquid-glass/dist/mri-liquid-glass.iife.min.js` (or download it from the CDN) next to the page, add a `<script>` tag and list the file in the `files` block of `fxmanifest.lua`.
3. Start once at NUI boot: `startGameGlass()` (plain HTML: `MriLiquidGlass.startGameGlass()`). Not on every screen open.
4. Decide per element. Replace `backdrop-filter` (also Tailwind `backdrop-blur*`) only where the blur should show the game behind it: panels, HUD pieces and buttons that float directly over the game. Keep `backdrop-filter` where it blurs other NUI content (a modal over a panel, a menu over a list): that works in FiveM, and this library would show the game instead of that content. For the replaced ones: remove the backdrop-filter, add `data-glass` (large panels with text) or `data-glass="liquid"` (buttons, pills, small highlighted pieces), and keep a low translucent background (white at 0.04 to 0.10 alpha) as tint.
5. Make `html`, `body` and the app root background transparent, and give the app root `position: relative; z-index: 1`.
6. Add `[data-glass-backdrop="bright"] { color: <dark color>; }` so text stays readable over bright scenes.
7. Screens that close: remove their markup from the DOM (the render loop stops with no glass on screen).
8. Outside the game the library is off; for browser development pass `fallbackImage` with a game screenshot.
9. Report what changed and say that the real effect must be checked in game (FiveM), not in the browser.

## Docs

- [For AI agents](https://mur4i.github.io/mri-fivem-liquid-glass/guide/ai)
- [Contributing](https://mur4i.github.io/mri-fivem-liquid-glass/guide/contributing)
- [FiveM resource](https://mur4i.github.io/mri-fivem-liquid-glass/guide/fivem)
- [React, Vue, Svelte](https://mur4i.github.io/mri-fivem-liquid-glass/guide/frameworks)
- [Quick start](https://mur4i.github.io/mri-fivem-liquid-glass/guide/getting-started)
- [How it works](https://mur4i.github.io/mri-fivem-liquid-glass/guide/how-it-works)
- [Introduction](https://mur4i.github.io/mri-fivem-liquid-glass/guide/)
- [Markup](https://mur4i.github.io/mri-fivem-liquid-glass/guide/markup)
- [Options](https://mur4i.github.io/mri-fivem-liquid-glass/guide/options)
- [Performance](https://mur4i.github.io/mri-fivem-liquid-glass/guide/performance)
- [Shapes and lenses](https://mur4i.github.io/mri-fivem-liquid-glass/guide/shapes-and-lenses)
- [Troubleshooting](https://mur4i.github.io/mri-fivem-liquid-glass/guide/troubleshooting)

## API

- [version.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/version.json)
- [options.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/options.json)
- [attributes.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/attributes.json)
- [presets.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/presets.json)
- [showcase.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/showcase.json)
- [index.json](https://mur4i.github.io/mri-fivem-liquid-glass/api/v1/index.json)

## Contributing as an AI agent

If you improved this library while using it, send the change upstream as a pull request: https://github.com/mur4i/mri-fivem-liquid-glass (read AGENTS.md first). Full text: https://mur4i.github.io/mri-fivem-liquid-glass/llms-full.txt