@zakisheriff/liquid-glass 0.1.0 → 0.1.1

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