@zakisheriff/liquid-glass 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,11 @@
22
22
  <br />
23
23
  <br />
24
24
 
25
- **[View on GitHub: https://github.com/zakisheriff/Liquid-Glass](https://github.com/zakisheriff/Liquid-Glass)**
25
+ **[Website: https://liquidglass.theatom.lk](https://liquidglass.theatom.lk)**
26
+
27
+ **[GitHub: https://github.com/zakisheriff/Liquid-Glass](https://github.com/zakisheriff/Liquid-Glass)**
28
+
29
+ **[npm: https://www.npmjs.com/package/@zakisheriff/liquid-glass](https://www.npmjs.com/package/@zakisheriff/liquid-glass)**
26
30
 
27
31
  </div>
28
32
 
@@ -30,341 +34,585 @@
30
34
 
31
35
  > **"Glass should feel physical, not painted on."**
32
36
  >
33
- > `@zakisheriff/liquid-glass` brings Apple's liquid glass aesthetic to React.
34
- > Built with layered shadows, prismatic borders, animated shine overlays, and native CSS blur, it turns ordinary interface elements into tactile glass surfaces.
37
+ > `@zakisheriff/liquid-glass` brings iOS-style liquid glass surfaces to React with layered shadows, prismatic borders, refraction filters, animated shine, and native CSS blur.
35
38
 
36
39
  ---
37
40
 
38
- ## 🌟 Vision
39
-
40
- Liquid Glass exists to be:
41
+ ## Why Use It?
41
42
 
42
- - **A polished React component library** for building premium glass interfaces quickly
43
- - **A native CSS-first design system** with no heavy visual runtime
44
- - **A reusable foundation** for buttons, cards, inputs, sheets, navigation, and custom glass components
43
+ - **Ready-made glass components** for buttons, cards, inputs, sheets, nav bars, and sliders
44
+ - **Real depth and refraction** using layered CSS, `backdrop-filter`, masks, gradients, and SVG displacement filters
45
+ - **TypeScript-first API** with exported prop types for every component
46
+ - **No design framework required** because the package ships its own CSS
47
+ - **Customizable surfaces** through intensity, tint, shimmer, thickness, radius, and layout props
45
48
 
46
49
  ---
47
50
 
48
- ## ✨ Why Liquid Glass?
51
+ ## Install
49
52
 
50
- Most glassmorphism is just a translucent rectangle with blur.
51
- Liquid Glass goes deeper with **physical depth, refracted edges, animated highlights, and tactile interaction states**.
52
-
53
- It is designed for teams who want Apple-inspired surfaces without rebuilding the same effect from scratch in every project.
54
-
55
- ---
53
+ ```bash
54
+ npm install @zakisheriff/liquid-glass
55
+ ```
56
56
 
57
- ## 🎨 Apple-Inspired Liquid Glass Design
57
+ ```bash
58
+ yarn add @zakisheriff/liquid-glass
59
+ ```
58
60
 
59
- - **Layered Surface Depth**
60
- Multiple inset and outer shadows create the feeling of glass floating above the interface.
61
+ ```bash
62
+ pnpm add @zakisheriff/liquid-glass
63
+ ```
61
64
 
62
- - **Prismatic Edge Refraction**
63
- Conic-gradient borders with mask compositing simulate light catching the rim of glass.
65
+ ---
64
66
 
65
- - **Animated Shine**
66
- Subtle hover glints and shimmer states make interactive elements feel alive.
67
+ ## Setup
67
68
 
68
- - **Native Backdrop Blur**
69
- CSS `backdrop-filter: blur()` creates real frosted-glass depth over page content.
69
+ Import the stylesheet once in your app entry file.
70
70
 
71
- - **System-Friendly Styling**
72
- Components inherit typography and layout naturally, so they fit inside existing React apps.
71
+ ```tsx
72
+ import '@zakisheriff/liquid-glass/styles.css';
73
+ ```
73
74
 
74
- ---
75
+ Then import only the components you need.
75
76
 
76
- ## 🧩 Component Library
77
+ ```tsx
78
+ import {
79
+ GlassButton,
80
+ GlassCard,
81
+ GlassInput,
82
+ GlassNav,
83
+ GlassSheet,
84
+ GlassSlider,
85
+ LiquidGlassFilter,
86
+ } from '@zakisheriff/liquid-glass';
87
+ ```
77
88
 
78
- - **GlassButton**
79
- Pill-shaped action button with depth, shimmer, variants, sizes, and press feedback.
89
+ For the cleanest output, wrap the area using glass components with `LiquidGlassFilter`. Components still work without it, but the provider renders one shared SVG filter set instead of each component injecting its own local filter.
80
90
 
81
- - **GlassCard**
82
- Flexible glass container for panels, sections, previews, and grouped content.
91
+ ```tsx
92
+ import { LiquidGlassFilter } from '@zakisheriff/liquid-glass';
93
+ import '@zakisheriff/liquid-glass/styles.css';
83
94
 
84
- - **GlassInput**
85
- Glass-surfaced text input with focus animation and optional floating label.
95
+ export default function App() {
96
+ return (
97
+ <LiquidGlassFilter>
98
+ <YourApp />
99
+ </LiquidGlassFilter>
100
+ );
101
+ }
102
+ ```
86
103
 
87
- - **GlassSheet**
88
- Bottom sheet/modal overlay with smooth slide-up animation and glass backdrop.
104
+ If you use Next.js App Router, use these components inside a client component because they rely on browser interaction APIs.
89
105
 
90
- - **GlassNav**
91
- Pill navigation with glass surface and sliding active indicator.
106
+ ```tsx
107
+ 'use client';
92
108
 
93
- - **LiquidGlassFilter**
94
- Advanced SVG filter provider for custom glass experiments.
109
+ import { GlassButton } from '@zakisheriff/liquid-glass';
110
+ import '@zakisheriff/liquid-glass/styles.css';
111
+ ```
95
112
 
96
113
  ---
97
114
 
98
- ## 🪄 Hooks for Custom Glass
115
+ ## Quick Example
99
116
 
100
- - **useGlassEffect**
101
- Generates glass styles and filter IDs for building custom glass components.
117
+ ```tsx
118
+ import { GlassButton, GlassCard, LiquidGlassFilter } from '@zakisheriff/liquid-glass';
119
+ import '@zakisheriff/liquid-glass/styles.css';
102
120
 
103
- - **useGlassAnimation**
104
- Tracks hover, press, and focus states for interactive glass behavior.
121
+ export default function App() {
122
+ return (
123
+ <LiquidGlassFilter>
124
+ <main style={{ minHeight: '100vh', padding: 40, background: '#f3f4f6' }}>
125
+ <GlassCard padding="32px" radius="28px" intensity={6} shimmer>
126
+ <h2>Hello, Liquid Glass</h2>
127
+ <p>Build tactile glass interfaces with React.</p>
128
+
129
+ <GlassButton size="lg" onClick={() => alert('Clicked!')}>
130
+ Get Started
131
+ </GlassButton>
132
+ </GlassCard>
133
+ </main>
134
+ </LiquidGlassFilter>
135
+ );
136
+ }
137
+ ```
105
138
 
106
139
  ---
107
140
 
108
- ## 📁 Project Structure
141
+ ## Shared Visual Props
109
142
 
110
- ```text
111
- liquid-glass/
112
- ├── src/
113
- │ ├── index.ts # Public package exports
114
- │ ├── components/
115
- │ │ ├── GlassButton/
116
- │ │ │ ├── GlassButton.tsx # Liquid glass button component
117
- │ │ │ ├── GlassButton.css # Button-specific styles
118
- │ │ │ └── index.ts # Component barrel export
119
- │ │ ├── GlassCard/
120
- │ │ │ ├── GlassCard.tsx # Glass container component
121
- │ │ │ └── index.ts
122
- │ │ ├── GlassInput/
123
- │ │ │ ├── GlassInput.tsx # Glass text input
124
- │ │ │ └── index.ts
125
- │ │ ├── GlassSheet/
126
- │ │ │ ├── GlassSheet.tsx # Bottom sheet/modal surface
127
- │ │ │ └── index.ts
128
- │ │ └── GlassNav/
129
- │ │ ├── GlassNav.tsx # Glass navigation component
130
- │ │ └── index.ts
131
- │ ├── hooks/
132
- │ │ ├── useGlassAnimation.ts # Interaction state hook
133
- │ │ └── useGlassEffect.ts # Custom glass style hook
134
- │ ├── filters/
135
- │ │ └── LiquidGlassFilter.tsx # Advanced SVG filter provider
136
- │ └── styles/
137
- │ └── base.css # Core liquid glass styles
138
- ├── package.json # Package metadata and scripts
139
- ├── tsconfig.json # TypeScript configuration
140
- └── tsup.config.ts # Build configuration
141
- ```
143
+ Most visual components use the same glass controls:
142
144
 
143
- ---
144
-
145
- ## 🚀 Quick Start
145
+ | Prop | Type | Default | What it does |
146
+ |------|------|---------|--------------|
147
+ | `intensity` | `number` | `5` | Controls refraction and blur strength. Values are clamped from `1` to `10`. |
148
+ | `tint` | `string` | `undefined` | Adds a CSS color overlay such as `rgba(0, 122, 255, 0.14)` or `#ffffff22`. |
149
+ | `shimmer` | `boolean` | `true` | Enables animated shine/reflection effects where supported. |
150
+ | `thickness` | `number` | `1` | Controls bevel/border thickness in pixels where supported. |
146
151
 
147
- ### Prerequisites
152
+ Use low intensity for subtle UI, mid intensity for standard panels, and high intensity for strong refraction demos.
148
153
 
149
- - **Node.js** (v18+ recommended)
150
- - **React** (v17+)
151
- - **React DOM** (v17+)
154
+ ---
152
155
 
153
- ### 1. Install the Package
156
+ ## GlassButton
154
157
 
155
- ```bash
156
- npm install @zakisheriff/liquid-glass
157
- ```
158
+ Use `GlassButton` for primary actions, secondary actions, destructive actions, icon buttons, and pill-shaped CTA buttons. It renders a real `<button>`, so native button props like `type`, `disabled`, `aria-label`, `onClick`, and `form` work.
158
159
 
159
- ```bash
160
- yarn add @zakisheriff/liquid-glass
161
- ```
160
+ ```tsx
161
+ import { GlassButton } from '@zakisheriff/liquid-glass';
162
162
 
163
- ```bash
164
- pnpm add @zakisheriff/liquid-glass
163
+ function Actions() {
164
+ return (
165
+ <div style={{ display: 'flex', gap: 12 }}>
166
+ <GlassButton size="lg" onClick={() => console.log('Save')}>
167
+ Save Changes
168
+ </GlassButton>
169
+
170
+ <GlassButton variant="ghost" shimmer={false}>
171
+ Cancel
172
+ </GlassButton>
173
+
174
+ <GlassButton variant="destructive">
175
+ Delete
176
+ </GlassButton>
177
+ </div>
178
+ );
179
+ }
165
180
  ```
166
181
 
167
- ### 2. Import Styles
182
+ Use the `size` prop for quick sizing, and use `style` when you need a fixed width.
168
183
 
169
184
  ```tsx
170
- import '@zakisheriff/liquid-glass/styles.css';
185
+ <GlassButton
186
+ size="md"
187
+ style={{ width: '100%' }}
188
+ >
189
+ Continue
190
+ </GlassButton>
171
191
  ```
172
192
 
173
- ### 3. Use Components
193
+ ### GlassButton Props
194
+
195
+ | Prop | Type | Default | What it does |
196
+ |------|------|---------|--------------|
197
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Changes height, font size, and minimum width. |
198
+ | `variant` | `'default' \| 'ghost' \| 'destructive'` | `'default'` | Sets the visual treatment. |
199
+ | `intensity` | `number` | `5` | Controls refraction strength. |
200
+ | `tint` | `string` | `undefined` | Adds a glass tint color. |
201
+ | `shimmer` | `boolean` | `true` | Enables the shine overlay. |
202
+ | `thickness` | `number` | `1` | Controls bevel thickness. |
203
+ | `children` | `React.ReactNode` | `undefined` | Button label or icon content. |
204
+ | Native button props | `ButtonHTMLAttributes<HTMLButtonElement>` | `-` | Supports `onClick`, `disabled`, `type`, `aria-*`, and more. |
205
+
206
+ ---
207
+
208
+ ## GlassCard
209
+
210
+ Use `GlassCard` as a glass surface for panels, forms, dashboards, settings groups, previews, and modal content. It renders a `<div>` and accepts normal div attributes.
174
211
 
175
212
  ```tsx
176
- import { GlassButton, GlassCard } from '@zakisheriff/liquid-glass';
177
- import '@zakisheriff/liquid-glass/styles.css';
213
+ import { GlassCard } from '@zakisheriff/liquid-glass';
178
214
 
179
- function App() {
215
+ function ProfileCard() {
180
216
  return (
181
- <main style={{ minHeight: '100vh', padding: 40, background: '#f3f4f6' }}>
182
- <GlassCard padding="32px" radius="24px" shimmer>
183
- <h2>Hello, Glass</h2>
184
- <p>Build tactile glass interfaces with React.</p>
185
-
186
- <GlassButton size="lg" shimmer onClick={() => alert('Clicked!')}>
187
- Get Started
188
- </GlassButton>
189
- </GlassCard>
190
- </main>
217
+ <GlassCard
218
+ intensity={6}
219
+ tint="rgba(255,255,255,0.12)"
220
+ padding="28px"
221
+ radius="32px"
222
+ >
223
+ <h2>Account</h2>
224
+ <p>Manage your profile and preferences.</p>
225
+ </GlassCard>
191
226
  );
192
227
  }
193
228
  ```
194
229
 
195
- ---
230
+ Use `padding` for inner spacing and `radius` for shape. Cards are best placed over a visible background, gradient, image, or soft color field so the blur/refraction is visible.
196
231
 
197
- ## 🎯 Key Features
232
+ ### GlassCard Props
198
233
 
199
- ✅ **React Components** — Buttons, cards, inputs, sheets, and navigation
200
- ✅ **TypeScript Support** — Fully typed exports for component props and hooks
201
- ✅ **CSS-First Effects** — Uses native CSS blur, shadows, masks, and gradients
202
- ✅ **Interactive States** — Hover, press, focus, shimmer, and disabled states
203
- ✅ **Custom Glass Hooks** — Build your own components with shared glass behavior
204
- ✅ **Small Package Surface** — Exports only components, hooks, filters, and styles
205
- ✅ **Framework Friendly** — Works in Vite, Next.js, Remix, and standard React apps
234
+ | Prop | Type | Default | What it does |
235
+ |------|------|---------|--------------|
236
+ | `intensity` | `number` | `5` | Controls refraction strength. |
237
+ | `tint` | `string` | `undefined` | Adds a glass tint color. |
238
+ | `shimmer` | `boolean` | `true` | Enables animated border shine. |
239
+ | `thickness` | `number` | `1` | Controls bevel thickness. |
240
+ | `padding` | `string` | `'24px'` | Sets inner content padding. |
241
+ | `radius` | `string` | `'20px'` | Sets border radius, for example `'24px'` or `'36px'`. |
242
+ | `children` | `React.ReactNode` | `undefined` | Card content. |
243
+ | Native div props | `HTMLAttributes<HTMLDivElement>` | `-` | Supports `className`, `style`, `id`, `role`, and more. |
206
244
 
207
245
  ---
208
246
 
209
- ## 🔧 Tech Stack
247
+ ## GlassInput
210
248
 
211
- ### Runtime
212
- - **React** — Component model and rendering
213
- - **React DOM** — DOM integration
214
- - **CSS** — Liquid glass visuals, blur, masks, and animations
249
+ Use `GlassInput` for controlled text fields with a floating label and glass focus state.
215
250
 
216
- ### Development
217
- - **TypeScript** — Static types and public declaration files
218
- - **Tsup** — Library bundling for ESM and CommonJS
219
- - **npm** — Package publishing workflow
251
+ ```tsx
252
+ import { useState } from 'react';
253
+ import { GlassInput } from '@zakisheriff/liquid-glass';
220
254
 
221
- ---
255
+ function LoginForm() {
256
+ const [email, setEmail] = useState('');
222
257
 
223
- ## 📦 Package Exports
258
+ return (
259
+ <GlassInput
260
+ label="Email"
261
+ placeholder="you@example.com"
262
+ value={email}
263
+ onChange={(event) => setEmail(event.target.value)}
264
+ autoComplete="email"
265
+ intensity={5}
266
+ />
267
+ );
268
+ }
269
+ ```
224
270
 
225
- ### Components
226
- - `GlassButton` — Action button with liquid glass styling
227
- - `GlassCard` — Glass content container
228
- - `GlassInput` — Styled input surface
229
- - `GlassSheet` — Modal/bottom sheet component
230
- - `GlassNav` — Pill navigation component
231
- - `LiquidGlassFilter` — Advanced filter provider
271
+ The input is controlled through `value` and `onChange`. The `label` floats when the field is focused or has a value.
232
272
 
233
- ### Hooks
234
- - `useGlassEffect` — Generate reusable glass styles
235
- - `useGlassAnimation` — Track interactive component states
273
+ ### GlassInput Props
236
274
 
237
- ### Styles
238
- - `@zakisheriff/liquid-glass/styles.css` — Core stylesheet
275
+ | Prop | Type | Default | What it does |
276
+ |------|------|---------|--------------|
277
+ | `label` | `string` | `undefined` | Floating label displayed inside the glass field. |
278
+ | `placeholder` | `string` | `undefined` | Native input placeholder. |
279
+ | `value` | `string` | `undefined` | Controlled input value. |
280
+ | `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | `undefined` | Change handler for controlled state. |
281
+ | `intensity` | `number` | `5` | Controls refraction strength. |
282
+ | `tint` | `string` | `undefined` | Adds a glass tint color. |
283
+ | Native input props | `InputHTMLAttributes<HTMLInputElement>` | `-` | Supports `type`, `name`, `required`, `autoComplete`, `disabled`, and more. |
239
284
 
240
285
  ---
241
286
 
242
- ## 🧪 Component Examples
287
+ ## GlassSlider
243
288
 
244
- ### GlassButton
289
+ Use `GlassSlider` for range controls. It renders a native range input overlay for accessibility, while the visual layer uses liquid glass.
245
290
 
246
- ```tsx
247
- <GlassButton size="lg" variant="default" shimmer onClick={handleClick}>
248
- Get the App
249
- </GlassButton>
250
- ```
291
+ There are two modes:
292
+
293
+ - `showThumb={false}` creates an iOS Control Center style block slider
294
+ - `showThumb={true}` creates a classic track slider with a circular knob
251
295
 
252
- ### GlassCard
296
+ ### Control Center Block Slider
253
297
 
254
298
  ```tsx
255
- <GlassCard padding="24px" radius="20px" shimmer>
256
- <p>Content goes here</p>
257
- </GlassCard>
299
+ import { useState } from 'react';
300
+ import { GlassSlider } from '@zakisheriff/liquid-glass';
301
+
302
+ function VolumeControl() {
303
+ const [volume, setVolume] = useState(46);
304
+
305
+ return (
306
+ <GlassSlider
307
+ min={0}
308
+ max={100}
309
+ value={volume}
310
+ onChange={setVolume}
311
+ showThumb={false}
312
+ label="Volume"
313
+ icon={<span aria-hidden>🔊</span>}
314
+ intensity={6}
315
+ />
316
+ );
317
+ }
258
318
  ```
259
319
 
260
- ### GlassInput
320
+ ### Classic Thumb Slider
261
321
 
262
322
  ```tsx
263
- <GlassInput
264
- label="Email"
265
- placeholder="you@example.com"
266
- value={email}
267
- onChange={(event) => setEmail(event.target.value)}
268
- />
323
+ function HueControl() {
324
+ const [hue, setHue] = useState(180);
325
+
326
+ return (
327
+ <GlassSlider
328
+ min={0}
329
+ max={360}
330
+ value={hue}
331
+ onChange={setHue}
332
+ showThumb
333
+ label="Hue"
334
+ />
335
+ );
336
+ }
269
337
  ```
270
338
 
271
- ### GlassSheet
339
+ ### GlassSlider Props
340
+
341
+ | Prop | Type | Default | What it does |
342
+ |------|------|---------|--------------|
343
+ | `value` | `number \| string \| readonly string[]` | `0` | Current range value. Use a number for best results. |
344
+ | `min` | `number \| string` | `0` | Minimum range value. |
345
+ | `max` | `number \| string` | `100` | Maximum range value. |
346
+ | `onChange` | `(value: number) => void` | `undefined` | Receives the numeric slider value. |
347
+ | `showThumb` | `boolean` | `true` | Shows the circular knob when `true`; uses block-fill style when `false`. |
348
+ | `icon` | `React.ReactNode` | `undefined` | Optional icon shown on the left inside the track. |
349
+ | `label` | `string` | `undefined` | Optional label shown inside the track. |
350
+ | `intensity` | `number` | `5` | Controls refraction strength. |
351
+ | `tint` | `string` | `undefined` | Adds a glass tint color. |
352
+ | `shimmer` | `boolean` | `true` | Enables shine on the active fill. |
353
+ | `thickness` | `number` | `1` | Controls bevel thickness. |
354
+ | Native range props | `InputHTMLAttributes<HTMLInputElement>` | `-` | Supports `step`, `disabled`, `aria-label`, and more. |
355
+
356
+ ---
357
+
358
+ ## GlassNav
359
+
360
+ Use `GlassNav` for segmented controls, tab bars, and compact navigation. It manages only visuals and click events; you own the active state.
272
361
 
273
362
  ```tsx
274
- <GlassSheet open={isOpen} onClose={() => setIsOpen(false)}>
275
- <h3>Sheet Content</h3>
276
- <p>This slides up from the bottom.</p>
277
- </GlassSheet>
363
+ import { useState } from 'react';
364
+ import { GlassNav } from '@zakisheriff/liquid-glass';
365
+
366
+ const tabs = [
367
+ { label: 'Overview' },
368
+ { label: 'Buttons' },
369
+ { label: 'Inputs' },
370
+ ];
371
+
372
+ function Tabs() {
373
+ const [activeTab, setActiveTab] = useState(0);
374
+
375
+ return (
376
+ <GlassNav
377
+ items={tabs}
378
+ activeIndex={activeTab}
379
+ onChange={setActiveTab}
380
+ intensity={5}
381
+ />
382
+ );
383
+ }
278
384
  ```
279
385
 
280
- ### GlassNav
386
+ Each item can include an icon.
281
387
 
282
388
  ```tsx
283
389
  <GlassNav
284
390
  items={[
285
- { label: 'Home' },
286
- { label: 'About' },
287
- { label: 'Contact' },
391
+ { label: 'Home', icon: <HomeIcon /> },
392
+ { label: 'Settings', icon: <SettingsIcon /> },
288
393
  ]}
289
- activeIndex={activeTab}
290
- onChange={setActiveTab}
394
+ activeIndex={activeIndex}
395
+ onChange={setActiveIndex}
291
396
  />
292
397
  ```
293
398
 
399
+ ### GlassNav Props
400
+
401
+ | Prop | Type | Default | What it does |
402
+ |------|------|---------|--------------|
403
+ | `items` | `{ label: string; icon?: React.ReactNode }[]` | Required | Items rendered as tabs. |
404
+ | `activeIndex` | `number` | `0` | Zero-based active item index. |
405
+ | `onChange` | `(index: number) => void` | `undefined` | Called when a nav item is clicked. |
406
+ | `intensity` | `number` | `5` | Controls refraction strength. |
407
+
294
408
  ---
295
409
 
296
- ## 🧠 How It Works
410
+ ## GlassSheet
297
411
 
298
- Liquid Glass is built with a multi-layer CSS approach:
412
+ Use `GlassSheet` for bottom sheets, action drawers, mobile menus, and lightweight modal panels. You control it with an `open` boolean.
299
413
 
300
- - **Surface Layer** — Semi-transparent gradients and `backdrop-filter` create the frosted base.
301
- - **Depth Shadows** — Carefully layered `box-shadow` values create physical depth and press feedback.
302
- - **Prismatic Border** — Masked conic gradients create a refractive rim around the surface.
303
- - **Shine Overlay** — Animated light streaks simulate glints moving across the component.
304
- - **Motion Curve** — `cubic-bezier(0.25, 1, 0.5, 1)` keeps transitions soft and tactile.
414
+ ```tsx
415
+ import { useState } from 'react';
416
+ import { GlassButton, GlassSheet } from '@zakisheriff/liquid-glass';
417
+
418
+ function SettingsSheet() {
419
+ const [open, setOpen] = useState(false);
420
+
421
+ return (
422
+ <>
423
+ <GlassButton onClick={() => setOpen(true)}>
424
+ Open Settings
425
+ </GlassButton>
426
+
427
+ <GlassSheet open={open} onClose={() => setOpen(false)} intensity={6}>
428
+ <h2>Settings</h2>
429
+ <p>Sheet content goes here.</p>
430
+
431
+ <GlassButton onClick={() => setOpen(false)}>
432
+ Done
433
+ </GlassButton>
434
+ </GlassSheet>
435
+ </>
436
+ );
437
+ }
438
+ ```
439
+
440
+ The sheet closes when the backdrop is clicked or when Escape is pressed. It also locks body scrolling while mounted.
441
+
442
+ ### GlassSheet Props
443
+
444
+ | Prop | Type | Default | What it does |
445
+ |------|------|---------|--------------|
446
+ | `open` | `boolean` | Required | Controls whether the sheet is visible. |
447
+ | `onClose` | `() => void` | `undefined` | Called by backdrop click or Escape key. |
448
+ | `intensity` | `number` | `5` | Controls refraction strength. |
449
+ | `tint` | `string` | `undefined` | Adds a glass tint color. |
450
+ | `children` | `React.ReactNode` | `undefined` | Sheet content. |
305
451
 
306
452
  ---
307
453
 
308
- ## 🌐 Browser Support
454
+ ## LiquidGlassFilter
455
+
456
+ Use `LiquidGlassFilter` once near the top of your app or page. It renders shared SVG filter definitions for refraction levels `1` through `10`.
457
+
458
+ ```tsx
459
+ import { LiquidGlassFilter } from '@zakisheriff/liquid-glass';
460
+
461
+ function Root() {
462
+ return (
463
+ <LiquidGlassFilter>
464
+ <App />
465
+ </LiquidGlassFilter>
466
+ );
467
+ }
468
+ ```
309
469
 
310
- ✅ **Chrome 89+**
311
- ✅ **Edge 89+**
312
- ✅ **Safari 15.4+**
313
- ✅ **Firefox 103+**
470
+ You can skip it for quick demos because each component can inject its own filter fallback, but using the provider is cleaner for production apps.
314
471
 
315
472
  ---
316
473
 
317
- ## 🛠️ Development
474
+ ## Hooks
318
475
 
319
- ### Clone the Repository
476
+ ### useGlassEffect
320
477
 
321
- ```bash
322
- git clone https://github.com/zakisheriff/Liquid-Glass.git
323
- cd liquid-glass
478
+ Use `useGlassEffect` when building your own custom glass component. It returns a `style` object with glass CSS variables and a matching `filterId`.
479
+
480
+ ```tsx
481
+ import { useGlassEffect } from '@zakisheriff/liquid-glass';
482
+
483
+ function CustomGlassPanel() {
484
+ const { style, filterId } = useGlassEffect({
485
+ intensity: 7,
486
+ tint: 'rgba(0, 122, 255, 0.14)',
487
+ shimmer: true,
488
+ thickness: 2,
489
+ blur: 18,
490
+ });
491
+
492
+ return (
493
+ <div data-liquid-glass style={style}>
494
+ Custom glass panel using {filterId}
495
+ </div>
496
+ );
497
+ }
498
+ ```
499
+
500
+ ### useGlassAnimation
501
+
502
+ Use `useGlassAnimation` when creating custom interactive glass elements. It gives you hover, press, and focus state plus pointer/focus handlers.
503
+
504
+ ```tsx
505
+ import { useGlassAnimation } from '@zakisheriff/liquid-glass';
506
+
507
+ function CustomGlassButton() {
508
+ const { isHovered, isPressed, isFocused, handlers } = useGlassAnimation();
509
+
510
+ return (
511
+ <button
512
+ {...handlers}
513
+ style={{
514
+ transform: isPressed ? 'scale(0.98)' : 'scale(1)',
515
+ opacity: isHovered || isFocused ? 1 : 0.86,
516
+ }}
517
+ >
518
+ Custom
519
+ </button>
520
+ );
521
+ }
324
522
  ```
325
523
 
326
- ### Install Dependencies
524
+ ---
525
+
526
+ ## Styling Tips
527
+
528
+ - Put glass components over a visible background, image, gradient, or soft color surface so blur/refraction has something to bend.
529
+ - Use `intensity={3}` to `intensity={6}` for production UI and `intensity={7}` to `intensity={10}` for dramatic demos.
530
+ - Use subtle tint values such as `rgba(0, 122, 255, 0.12)` instead of fully opaque colors.
531
+ - Keep `LiquidGlassFilter` mounted once around repeated glass components for cleaner DOM output.
532
+ - Import `@zakisheriff/liquid-glass/styles.css` only once.
533
+
534
+ ---
535
+
536
+ ## Browser Support
537
+
538
+ - Chrome 89+
539
+ - Edge 89+
540
+ - Safari 15.4+
541
+ - Firefox 103+
542
+
543
+ `backdrop-filter` support is required for the full liquid glass look.
544
+
545
+ ---
546
+
547
+ ## Project Structure
548
+
549
+ ```text
550
+ liquid-glass/
551
+ ├── src/
552
+ │ ├── index.ts
553
+ │ ├── components/
554
+ │ │ ├── GlassButton/
555
+ │ │ ├── GlassCard/
556
+ │ │ ├── GlassInput/
557
+ │ │ ├── GlassNav/
558
+ │ │ ├── GlassSheet/
559
+ │ │ └── GlassSlider/
560
+ │ ├── filters/
561
+ │ │ └── LiquidGlassFilter.tsx
562
+ │ ├── hooks/
563
+ │ │ ├── useGlassAnimation.ts
564
+ │ │ └── useGlassEffect.ts
565
+ │ └── styles/
566
+ │ └── base.css
567
+ ├── demo/
568
+ ├── package.json
569
+ ├── tsconfig.json
570
+ └── tsup.config.ts
571
+ ```
572
+
573
+ ---
574
+
575
+ ## Development
327
576
 
328
577
  ```bash
578
+ git clone https://github.com/zakisheriff/Liquid-Glass.git
579
+ cd Liquid-Glass
329
580
  npm install
330
581
  ```
331
582
 
332
- ### Run the Build
583
+ Run the library build:
333
584
 
334
585
  ```bash
335
586
  npm run build
336
587
  ```
337
588
 
338
- ### Watch During Development
589
+ Watch the library build:
339
590
 
340
591
  ```bash
341
592
  npm run dev
342
593
  ```
343
594
 
344
- ---
345
-
346
- ## 🤝 Contributing
595
+ Run the demo:
347
596
 
348
- Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
597
+ ```bash
598
+ npm run demo
599
+ ```
349
600
 
350
601
  ---
351
602
 
352
- ## 📄 License
603
+ ## License
353
604
 
354
- MIT License — free to use in personal and commercial projects.
605
+ MIT License. Free for personal and commercial projects.
355
606
 
356
607
  ---
357
608
 
358
- ## ☕️ Support the Project
359
-
360
- If Liquid Glass helped you build a more beautiful interface or inspired your next project:
609
+ ## Support the Project
361
610
 
362
- - Consider buying me a coffee
363
- - It keeps development alive and motivates future updates
611
+ If Liquid Glass helped you build a better interface, you can support future updates here:
364
612
 
365
613
  <div align="center">
366
- <a href="https://buymeacoffee.com/zakisheriffw">
367
- <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="60" width="217">
614
+ <a href="https://buymeacoffee.com/theoneatom">
615
+ <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="60" width="217" alt="Buy Me A Coffee">
368
616
  </a>
369
617
  </div>
370
618