@ajuarezso/capacitor-liquid-glass 0.3.7 → 0.4.0

package/README.es.md

@@ -0,0 +1,163 @@
+# @ajuarezso/capacitor-liquid-glass
+
+> **Chrome nativo Liquid Glass de iOS 26 (TabBar + SearchBar + roadmap para más) en apps Capacitor.**
+> El único plugin Capacitor (a 2026) que expone el `.glassEffect()` auténtico de Apple — no una aproximación con CSS `backdrop-filter`.
+
+[![npm version](https://img.shields.io/npm/v/@ajuarezso/capacitor-liquid-glass.svg)](https://www.npmjs.com/package/@ajuarezso/capacitor-liquid-glass)
+[![license](https://img.shields.io/npm/l/@ajuarezso/capacitor-liquid-glass.svg)](./LICENSE)
+
+> 🇬🇧 English version: [README.md](./README.md)
+
+## Por qué existe
+
+iOS 26 introdujo **Liquid Glass** — un material de sistema nuevo que combina blur + refracción dinámica + highlights de borde que se mueven con el contenido subyacente + transiciones de morphing + deformación reactiva al touch + variantes tinted/clear. Apple lo usa en el nuevo TabBar, NavigationBar, Sheets, Menus, el Dynamic Island, la app Music, el App Store, y Control Center.
+
+**A 2026, este es el único plugin Capacitor que expone el `UIGlassEffect` real** vía overlays nativos flotando arriba del WebView. Alternativas web como CSS `backdrop-filter`, `mix-blend-mode`, y filtros SVG pueden mimetizar el blur estático pero no reproducen:
+
+- Refracción dinámica (la luz se curva según el movimiento)
+- Highlights de borde que se mueven con el contenido subyacente
+- Transiciones morphing entre elementos (ej. el pill del tab deslizándose)
+- Deformación reactiva al touch (el "squish" al presionar)
+- Integración a nivel de sistema con Dynamic Island y Control Center
+
+Esto requiere shaders Metal privados que Apple no expone al `WKWebView`. El único camino es un **overlay nativo** anclado arriba del WebView — exactamente lo que hace este plugin.
+
+## Qué hay shipped hoy (v0.3.x)
+
+| widget | iOS 26+ | iOS 15-25 | Android | Web |
+|---|---|---|---|---|
+| **TabBar** | ✅ Liquid Glass real | ⚠️ `UITabBar` clásico | ❌ no-op | ❌ no-op |
+| **SearchBar** | ✅ Liquid Glass real | ⚠️ `UISearchBar` clásico en contenedor blurred | ❌ no-op | ❌ no-op |
+
+En plataformas no soportadas (Android, Web, iOS < 26) el plugin es un no-op gracioso — tu fallback CSS/HTML sigue funcionando.
+
+## Instalación
+
+```bash
+npm install @ajuarezso/capacitor-liquid-glass
+npx cap sync ios
+```
+
+Target mínimo iOS: `15.0`. **Liquid Glass real requiere iOS 26+**; en versiones anteriores el `UITabBar` / `UISearchBar` nativo todavía renderiza pero sin el material Liquid Glass.
+
+## Quick start
+
+### TabBar
+
+```typescript
+import { LiquidGlass } from '@ajuarezso/capacitor-liquid-glass';
+
+await LiquidGlass.showTabBar({
+  items: [
+    { id: '/home',    label: 'Home',    sfSymbol: 'house' },
+    { id: '/search',  label: 'Buscar',  sfSymbol: 'magnifyingglass' },
+    { id: '/cart',    label: 'Carrito', sfSymbol: 'bag', badge: '3' },
+    { id: '/profile', label: 'Perfil',  sfSymbol: 'person' },
+  ],
+  selectedIndex: 0,
+  tintColor: '#FA7319',
+  tabBarStyle: 'liquidGlass',
+});
+
+await LiquidGlass.addListener('tabSelected', ({ id, index }) => {
+  console.log('Tab tapped:', id, index);
+});
+
+await LiquidGlass.updateTabBadge({ id: '/cart', badge: '5' });
+await LiquidGlass.setSelectedTab({ id: '/profile' });
+await LiquidGlass.hideTabBar();
+```
+
+### SearchBar
+
+```typescript
+await LiquidGlass.showSearchBar({
+  placeholder: 'Buscar',
+  cancelText: 'Cancelar',
+  tintColor: '#FA7319',
+});
+
+await LiquidGlass.addListener('searchTextChanged', ({ text }) => {
+  console.log('User typed:', text);
+});
+await LiquidGlass.addListener('searchSubmitted', ({ text }) => {
+  console.log('User submitted:', text);
+});
+await LiquidGlass.addListener('searchCancelled', () => {
+  console.log('User tapped cancel');
+});
+
+await LiquidGlass.clearSearchText();
+await LiquidGlass.hideSearchBar();
+```
+
+## API completa
+
+Ver `README.md` (inglés) para la API detallada. Resumen:
+
+- **TabBar**: `showTabBar`, `hideTabBar`, `setSelectedTab`, `updateTabBadge`, `getTabBarLayout`
+- **SearchBar**: `showSearchBar`, `hideSearchBar`, `clearSearchText`
+- **Events**: `tabSelected`, `tabBarLayoutChanged`, `searchTextChanged`, `searchSubmitted`, `searchCancelled`
+
+## Comparativa con alternativas
+
+| proyecto | plataforma | Liquid Glass real? | activo? |
+|---|---|---|---|
+| **@ajuarezso/capacitor-liquid-glass** | iOS Capacitor | **sí** (`UIGlassEffect` real) | sí (2026) |
+| CSS `backdrop-filter: blur(...)` | todos los webviews | no (solo blur estático) | n/a |
+| `@react-native-community/blur` | React Native | parcial (`UIBlurEffect`, sin `UIGlassEffect`) | sí |
+| `flutter_glassmorphism` | Flutter | no (solo CSS-equivalente) | sí |
+
+## Por qué no solo CSS `backdrop-filter`?
+
+Porque es un efecto fundamentalmente distinto:
+
+- **CSS `backdrop-filter: blur(20px)`** → solo blur estático de lo que está atrás. Nada más.
+- **iOS 26 Liquid Glass (`UIGlassEffect`)** → blur + refracción dinámica + highlights de borde que se mueven con el contenido + morphing entre elementos (el tab pill que desliza) + deformación reactiva al touch + variantes tinted + integración con Dynamic Island. Usa shaders Metal privados que Apple **no** expone al WKWebView.
+
+Si solo necesitás glassmorphism estático para una landing o app no-iOS, usá CSS. Si necesitás el look auténtico iOS 26 en una app Capacitor en iPhone, este plugin es el camino más corto.
+
+## Roadmap
+
+- [x] **v0.1**: TabBar con fondo Liquid Glass
+- [x] **v0.2**: SearchBar overlay
+- [x] **v0.3**: Variantes de estilo (`'default'` / `'ultraThin'` / `'transparent'` / `'liquidGlass'`)
+- [ ] NavigationBar (large title, items leading/trailing)
+- [ ] Toolbar (floating toolbar tipo Safari)
+- [ ] Alert (standard y destructive)
+- [ ] Sheet con detents
+- [ ] Menu / Popover
+- [ ] Equivalentes Android Material 3 Expressive
+
+PRs welcome.
+
+## Limitaciones
+
+1. **iOS 26 requerido para Liquid Glass real**. En iOS 15-25 el plugin sigue renderizando `UITabBar` / `UISearchBar` nativo pero sin el material Liquid Glass — cae a `UIBlurEffect.systemThinMaterial`.
+
+2. **Android es un no-op**. Equivalentes Material 3 Expressive están en roadmap pero no shipped. Renderizá tu propio fallback.
+
+3. **El overlay nativo flota arriba del WebView**, así que no anima con las transiciones del router web. Usá `hideTabBar()` cuando entrás a rutas fullscreen que no deben mostrar el tab bar.
+
+4. **App Store**: este plugin usa solo APIs públicas de Apple. Sin riesgo de API privada.
+
+## Keywords para discoverability
+
+Este plugin resuelve: capacitor liquid glass, ios 26 liquid glass capacitor, capacitor tab bar native, capacitor search bar native, ionic liquid glass, ios 26 UIGlassEffect capacitor, capacitor glassmorphism native, capacitor native chrome, capacitor UITabBar, capacitor UISearchBar, capacitor angular tab bar ios.
+
+Proyectos relacionados (alternativa o complementario):
+- CSS `backdrop-filter` (no Liquid Glass real, solo blur)
+- `@capacitor/status-bar` (concern distinto)
+- Librerías de blur para React Native (framework distinto)
+- Plugins community Capacitor para tab bars (HTML/CSS, no Liquid Glass nativo)
+
+## Repositorio
+
+- Source: https://github.com/anthonyjuarezsolis/capacitor-liquid-glass
+- Issues: https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues
+- npm: https://www.npmjs.com/package/@ajuarezso/capacitor-liquid-glass
+- Construido y verificado en iPhone 17 Pro Max con iOS 26.5
+
+## Licencia
+
+MIT © Anthony Juarez Solis — ver [LICENSE](./LICENSE)

package/README.md

@@ -1,10 +1,35 @@
 # @ajuarezso/capacitor-liquid-glass
 
-Native iOS 26 **Liquid Glass** chrome (TabBar, NavigationBar, Alerts, Sheets, Menus) for Capacitor apps. Falls back gracefully on iOS < 26 and Android (no-op), so your app keeps its own CSS chrome on unsupported platforms.
+> **Real iOS 26 Liquid Glass native chrome (TabBar + SearchBar + roadmap for more) for Capacitor apps.**
+> The only Capacitor plugin (as of 2026) that exposes Apple's authentic `.glassEffect()` rendering — not a CSS `backdrop-filter` approximation.
 
-This plugin exists because, as of 2026, no existing Capacitor plugin exposes the real iOS 26 `.glassEffect()` rendered by UIKit — only CSS `backdrop-filter` approximations. This plugin floats a real `UITabBar` (and friends) as a native overlay above your `WKWebView`, so you get the actual Apple-native morphing, refraction, and tint animations of Liquid Glass on iOS 26+.
+[![npm version](https://img.shields.io/npm/v/@ajuarezso/capacitor-liquid-glass.svg)](https://www.npmjs.com/package/@ajuarezso/capacitor-liquid-glass)
+[![license](https://img.shields.io/npm/l/@ajuarezso/capacitor-liquid-glass.svg)](./LICENSE)
 
-> Status: `0.1.0` — **TabBar only**. NavigationBar, Toolbar, Sheet, Alert, Menu, Popover are on the roadmap.
+> 🇪🇸 Versión en español: [README.es.md](./README.es.md)
+
+## Why this exists
+
+iOS 26 introduced **Liquid Glass** — a new system material that combines blur + dynamic refraction + edge highlights that shift with underlying content + morphing transitions + touch-reactive deformation + tinted/clear variants. Apple uses it for the new TabBar, NavigationBar, Sheets, Menus, the Dynamic Island, the Music app, the App Store, and Control Center.
+
+**As of 2026, this is the only Capacitor plugin that exposes the real `UIGlassEffect`** via native overlays floating above the WebView. Web alternatives like CSS `backdrop-filter`, `mix-blend-mode`, and SVG filters can mimic the static blur but cannot reproduce:
+
+- Dynamic refraction (light bending based on movement)
+- Edge highlights that shift with underlying content
+- Morphing transitions between elements (e.g., tab pill sliding between items)
+- Touch-reactive deformation (the "squish" when pressed)
+- System-level Dynamic Island and Control Center integration
+
+These require private Metal shaders that Apple does not expose to `WKWebView`. The only path is a **native overlay** anchored above the WebView — which is exactly what this plugin does.
+
+## What's shipped today (v0.3.x)
+
+| widget | iOS 26+ | iOS 15-25 | Android | Web |
+|---|---|---|---|---|
+| **TabBar** | ✅ Real Liquid Glass | ⚠️ Classic `UITabBar` | ❌ no-op | ❌ no-op |
+| **SearchBar** | ✅ Real Liquid Glass | ⚠️ Classic `UISearchBar` in blurred container | ❌ no-op | ❌ no-op |
+
+On unsupported platforms (Android, Web, iOS < 26) the plugin is a graceful no-op — your CSS/HTML fallback continues to work.
 
 ## Install
 
@@ -13,14 +38,15 @@ npm install @ajuarezso/capacitor-liquid-glass
 npx cap sync ios
 ```
 
-iOS minimum target: `15.0`. Real Liquid Glass requires **iOS 26+**; on older versions the native `UITabBar` still renders but without the Liquid Glass effect.
+iOS minimum target: `15.0`. **Real Liquid Glass requires iOS 26+**; on older iOS the native `UITabBar` / `UISearchBar` still renders but without the Liquid Glass material.
 
 ## Quick start
 
-```ts
+### TabBar
+
+```typescript
 import { LiquidGlass } from '@ajuarezso/capacitor-liquid-glass';
 
-// Show the native tab bar
 await LiquidGlass.showTabBar({
   items: [
     { id: '/home',    label: 'Home',    sfSymbol: 'house' },
@@ -30,121 +56,255 @@ await LiquidGlass.showTabBar({
   ],
   selectedIndex: 0,
   tintColor: '#FA7319',
+  tabBarStyle: 'liquidGlass',  // 'default' | 'ultraThin' | 'transparent' | 'liquidGlass'
 });
 
-// Listen for taps
 await LiquidGlass.addListener('tabSelected', ({ id, index }) => {
   console.log('Tab tapped:', id, index);
 });
 
-// Update badge without rebuilding the tab bar
 await LiquidGlass.updateTabBadge({ id: '/cart', badge: '5' });
-
-// Programmatically change the selected tab
 await LiquidGlass.setSelectedTab({ id: '/profile' });
-
-// Hide (e.g. when opening a fullscreen modal)
 await LiquidGlass.hideTabBar();
 ```
 
-## API
+### SearchBar
+
+```typescript
+await LiquidGlass.showSearchBar({
+  placeholder: 'Search',
+  cancelText: 'Cancel',
+  tintColor: '#FA7319',
+});
+
+await LiquidGlass.addListener('searchTextChanged', ({ text }) => {
+  console.log('User typed:', text);
+});
+await LiquidGlass.addListener('searchSubmitted', ({ text }) => {
+  console.log('User submitted:', text);
+});
+await LiquidGlass.addListener('searchCancelled', () => {
+  console.log('User tapped cancel');
+});
+
+await LiquidGlass.clearSearchText();
+await LiquidGlass.hideSearchBar();
+```
+
+## API reference
 
-### `showTabBar(options)`
+### TabBar
 
-| Option          | Type                    | Required | Description                                                 |
-| --------------- | ----------------------- | -------- | ----------------------------------------------------------- |
-| `items`         | `LiquidGlassTabItem[]`  | yes      | At least one item.                                          |
-| `selectedIndex` | `number`                | no       | Initial selection. Defaults to `0`.                         |
-| `tintColor`     | `string` (`#RRGGBB`)    | no       | Color of the selected pill. Defaults to the system tint.    |
+#### `showTabBar(options): Promise<void>`
 
-### `LiquidGlassTabItem`
+```typescript
+interface ShowTabBarOptions {
+  items: LiquidGlassTabItem[];
+  selectedIndex?: number;            // default 0
+  tintColor?: string;                 // '#RRGGBB'
+  tabBarStyle?: TabBarStyle;          // 'default' | 'ultraThin' | 'transparent' | 'liquidGlass'
+  containerElement?: string | HTMLElement;  // bind to an HTML element (see below)
+}
 
-```ts
 interface LiquidGlassTabItem {
-  /** Stable id emitted in `tabSelected` events. */
-  id: string;
-  /** Text under the icon. */
-  label: string;
-  /** SF Symbol name (e.g. 'house.fill'). */
-  sfSymbol: string;
-  /** Optional badge value (e.g. '3' or '•'). */
-  badge?: string;
+  id: string;          // stable id emitted in events
+  label: string;       // text under the icon
+  sfSymbol: string;    // SF Symbol name, e.g. 'house.fill'
+  badge?: string;      // '3' or '•' or undefined
 }
 ```
 
-### `hideTabBar()`
+#### `containerElement` — bind the bar to an HTML element (iOS)
 
-Hides the tab bar without destroying it. Use this when opening fullscreen modals, maps, or any UI that should temporarily own the screen. Call `showTabBar(...)` again to restore it.
+By default the tab bar pins itself to the bottom of the screen. Pass
+`containerElement` (an element `id`, a CSS selector, or the `HTMLElement`) to
+instead **glue the native bar to the bounds of an element in your layout** —
+the same idea as the Capacitor Google Maps placeholder element. ([#1](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues/1))
 
-### `setSelectedTab({ index?, id? })`
+```typescript
+await LiquidGlass.showTabBar({
+  items: [...],
+  containerElement: 'tab-bar-slot',  // <div id="tab-bar-slot"> in your DOM
+});
+```
 
-Updates the selected tab programmatically. Useful when the user navigates via a deep link, a button inside a page, or any source other than the tab bar itself.
+```html
+<!-- A placeholder that reserves where the native bar should sit. -->
+<div id="tab-bar-slot" style="
+  position: fixed; left: 16px; right: 16px; bottom: 24px;
+  height: calc(64px + env(safe-area-inset-bottom));">
+</div>
+```
 
-### `updateTabBadge({ id, badge })`
+How it works:
 
-Updates a single tab's badge **without** reconfiguring the whole bar (preserves selection). Pass an empty string or omit `badge` to clear.
+- The plugin measures the element's `getBoundingClientRect()` and positions the
+  native bar (an on-top overlay) to match — CSS px map 1:1 to UIKit points in a
+  WKWebView, so no scaling is applied.
+- It re-syncs automatically on `ResizeObserver` + scroll + rotation + keyboard
+  (`visualViewport`), all coalesced through `requestAnimationFrame` so a 120 Hz
+  scroll fires at most one reposition per frame.
+- The element is a **layout placeholder only** — keep it empty/transparent; the
+  native bar renders on top of it. Resolution and measurement happen in JS; the
+  `HTMLElement` never crosses the native bridge.
 
-### `getTabBarLayout()`
+> ⚠️ **Size the element to include `env(safe-area-inset-bottom)` when it sits at
+> the bottom edge.** The native bar fills exactly the element's rect — if the
+> element is shorter than the bar's natural height (~49 pt + safe area on
+> notched iPhones) the labels/icons get clipped. If the measured rect is `0` in
+> either dimension the plugin falls back to bottom-pinned.
 
-Returns the current `{ height, bottomSafeArea }` in points so you can reserve content padding.
+> ℹ️ Pure **position** changes of a `position: fixed` element that fire no
+> `scroll`/`resize`/`ResizeObserver` event won't auto re-sync. Call
+> `showTabBar(...)` again (cheap — it re-measures) after such a move, or use the
+> low-level `setTabBarBounds(...)` yourself.
 
-### Events
+#### `setTabBarBounds({ bounds }): Promise<void>`
 
-| Event                  | Payload                                     |
-| ---------------------- | ------------------------------------------- |
-| `tabSelected`          | `{ index: number, id: string }`             |
-| `tabBarLayoutChanged`  | `{ height: number, bottomSafeArea: number }` |
+Low-level escape hatch (iOS): reposition the bar to an explicit rect
+(`{ x, y, width, height }` in CSS px, viewport-relative). The binding layer
+drives this for you when you pass `containerElement`; call it directly only if
+you measure the element yourself. No-op on web/Android and when the bar is not
+shown.
 
-## Angular example
+#### `hideTabBar(): Promise<void>`
 
-```ts
-import { bindLiquidGlassNav } from './liquid-glass-nav';
+Hides without destroying configuration. Use for fullscreen modals / maps.
 
-export class CustomerLayout {
-  private readonly nav = bindLiquidGlassNav({
-    items: [
-      { id: '/home',    label: 'Home',    sfSymbol: 'house' },
-      { id: '/orders',  label: 'Orders',  sfSymbol: 'list.bullet.clipboard' },
-      { id: '/profile', label: 'Profile', sfSymbol: 'person' },
-    ],
-    isFullscreen: this.isFullscreen, // signal<boolean>
-  });
+#### `setSelectedTab({ index?, id? }): Promise<void>`
 
-  readonly useNativeTabBar = this.nav.useNativeTabBar;
+Programmatic selection (deep links, internal navigation).
+
+#### `updateTabBadge({ id, badge }): Promise<void>`
+
+Updates a single badge without reconfiguring the whole bar (preserves selection).
+
+#### `getTabBarLayout(): Promise<{ height, bottomSafeArea }>`
+
+Returns layout in points to reserve content padding.
+
+### SearchBar
+
+#### `showSearchBar(options?): Promise<void>`
+
+```typescript
+interface ShowSearchBarOptions {
+  placeholder?: string;
+  initialText?: string;
+  cancelText?: string;
+  tintColor?: string;
+  hideCancelButton?: boolean;
 }
 ```
 
-See the `example/` folder for a full wiring including router sync and HTML fallback for unsupported platforms.
+#### `hideSearchBar(): Promise<void>`
+#### `clearSearchText(): Promise<void>`
 
-## Platform behavior
+### Events
+
+| event | payload |
+|---|---|
+| `tabSelected` | `{ index: number, id: string }` |
+| `tabBarLayoutChanged` | `{ height: number, bottomSafeArea: number }` |
+| `searchTextChanged` | `{ text: string }` |
+| `searchSubmitted` | `{ text: string }` |
+| `searchCancelled` | `{}` |
+
+## Angular example
 
-| Widget       | iOS 26+              | iOS 15–25           | Android | Web        |
-| ------------ | -------------------- | ------------------- | ------- | ---------- |
-| TabBar       | ✅ Liquid Glass real | ⚠️ Classic UITabBar | ❌ no-op | ❌ no-op   |
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { LiquidGlass } from '@ajuarezso/capacitor-liquid-glass';
+import { Capacitor } from '@capacitor/core';
+import { Router } from '@angular/router';
+
+@Component({ selector: 'app-shell', template: '<router-outlet />' })
+export class AppShell {
+  private router = inject(Router);
+
+  async ngOnInit() {
+    if (!Capacitor.isNativePlatform()) return;
+
+    await LiquidGlass.showTabBar({
+      items: [
+        { id: '/home', label: 'Home', sfSymbol: 'house' },
+        { id: '/cart', label: 'Cart', sfSymbol: 'bag' },
+      ],
+      tabBarStyle: 'liquidGlass',
+    });
+
+    LiquidGlass.addListener('tabSelected', ({ id }) => {
+      this.router.navigate([id]);
+    });
+  }
+}
+```
 
-When the plugin is a no-op (Android, Web, iOS &lt; 26), render your own HTML / CSS fallback. The plugin exposes `Capacitor.getPlatform()` and your Angular / React code can conditionally swap to a `backdrop-filter` bar.
+For unsupported platforms (Android, Web), render your own CSS / Tailwind tab bar gated by `Capacitor.getPlatform()`.
+
+## Comparison with alternatives
+
+| project | platform | real Liquid Glass? | adoption | active? |
+|---|---|---|---|---|
+| **@ajuarezso/capacitor-liquid-glass** | iOS Capacitor | **yes** (real `UIGlassEffect`) | Anthony Juarez Solis | yes (2026) |
+| CSS `backdrop-filter: blur(...)` | all webviews | no (just static blur) | universal | n/a |
+| `@react-native-community/blur` | React Native | partial (UIBlurEffect, no `UIGlassEffect`) | RN community | yes |
+| `flutter_glassmorphism` | Flutter | no (just CSS-equivalent) | community | yes |
+| Tauri WKWebView native overlays | Tauri | not yet published | n/a | n/a |
 
 ## Why not just CSS `backdrop-filter`?
 
-Because it's not the same thing.
+Because it's a fundamentally different effect:
 
-- **CSS `backdrop-filter`** gives you blur. That's it.
-- **Liquid Glass** gives you blur + *dynamic refraction*, *edge highlights that shift with content*, *morphing between elements*, *touch-reactive deformation*, *tinted / clear variants*, and system-level Dynamic Island integration. These require private Metal shaders that Apple does not expose to `WKWebView`.
+- **CSS `backdrop-filter: blur(20px)`** → just static blur of what's behind. That's it.
+- **iOS 26 Liquid Glass (`UIGlassEffect`)** → blur + dynamic refraction + edge highlights that shift with content motion + morphing between elements (the tab pill that slides) + touch-reactive deformation + tint variants + system Dynamic Island integration. These use private Metal shaders Apple does **not** expose to WKWebView.
 
-This plugin is the shortest path to Apple-authentic Liquid Glass from a Capacitor app.
+If you only need static glassmorphism for a marketing site or non-iOS app, just use CSS. If you need the authentic Apple iOS 26 look on a Capacitor app running on iPhone, this plugin is the shortest path.
 
 ## Roadmap
 
-- [x] `TabBar`
-- [ ] `NavigationBar` (large title, leading/trailing items)
-- [ ] `Toolbar` (floating toolbar like Safari)
-- [ ] `Alert` (standard and destructive)
-- [ ] `Sheet` (with detents)
-- [ ] `Menu` / `Popover`
+- [x] **v0.1**: TabBar with Liquid Glass background
+- [x] **v0.2**: SearchBar overlay
+- [x] **v0.3**: Style variants (`'default'` / `'ultraThin'` / `'transparent'` / `'liquidGlass'`)
+- [x] **v0.4**: Bind the TabBar to an HTML element (`containerElement`) ([#1](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues/1))
+- [ ] NavigationBar (large title, leading/trailing items)
+- [ ] Toolbar (floating toolbar like Safari)
+- [ ] Alert (standard and destructive)
+- [ ] Sheet with detents
+- [ ] Menu / Popover
 - [ ] Android Material 3 Expressive equivalents
 
 PRs welcome.
 
+## Limitations
+
+1. **iOS 26 required for real Liquid Glass**. On iOS 15-25 the plugin still renders native `UITabBar` / `UISearchBar` but without the Liquid Glass material — falls back to `UIBlurEffect.systemThinMaterial`.
+
+2. **Android is a no-op**. Material 3 Expressive equivalents are on the roadmap but not yet shipped. Render your own fallback.
+
+3. **The native overlay floats above the WebView**, so it does not animate with router transitions of your web router. Use `hideTabBar()` when entering fullscreen routes that shouldn't show the tab bar.
+
+4. **App Store**: this plugin uses public Apple APIs only. No private API risk.
+
+5. **`containerElement` binding** re-syncs on resize/scroll/rotation/keyboard, but **not** on a pure position move of a `position: fixed` element that emits no DOM event. Re-call `showTabBar(...)` (or `setTabBarBounds(...)`) after such a move. Also size the bound element to include the bottom safe area (see the `containerElement` docs above) or the bar gets clipped.
+
+## Keywords for discoverability
+
+This plugin solves: capacitor liquid glass, ios 26 liquid glass capacitor, capacitor tab bar native, capacitor search bar native, ionic liquid glass, ios 26 UIGlassEffect capacitor, capacitor glassmorphism native, capacitor native chrome, capacitor UITabBar, capacitor UISearchBar, capacitor angular tab bar ios, react native vs capacitor liquid glass.
+
+Related projects this is an alternative to:
+- CSS `backdrop-filter` (not real Liquid Glass, just blur)
+- `@capacitor/status-bar` (different concern — status bar only)
+- React Native blur libraries (different framework)
+- Capacitor community plugins for tab bars (use HTML/CSS, not native Liquid Glass)
+
+## Repository
+
+- Source: https://github.com/anthonyjuarezsolis/capacitor-liquid-glass
+- Issues: https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues
+- npm: https://www.npmjs.com/package/@ajuarezso/capacitor-liquid-glass
+- Built and verified on iPhone 17 Pro Max running iOS 26.5
+
 ## License
 
-MIT © Anthony Juarez Solis
+MIT © Anthony Juarez Solis — see [LICENSE](./LICENSE)

package/dist/esm/definitions.d.ts

@@ -29,6 +29,47 @@ export interface ShowTabBarOptions {
     tintColor?: string;
     /** Visual style of the tab bar background. Defaults to `'default'`. */
     tabBarStyle?: TabBarStyle;
+    /**
+     * Opt-in: bind the native tab bar to an HTML element's bounds instead of
+     * pinning it to the bottom of the screen. Pass an element `id`, a CSS
+     * selector, or the `HTMLElement` itself. The plugin measures the element and
+     * keeps the native bar glued to it across resize / rotation / keyboard /
+     * scroll.
+     *
+     * When omitted (default), the bar stays pinned to the bottom of the host view
+     * — identical to previous behaviour, no regression.
+     *
+     * Notes:
+     *  - iOS only. Ignored on web/Android.
+     *  - The element acts purely as a layout placeholder; size it (width/height
+     *    incl. safe-area) the way you want the native bar to look. The native bar
+     *    renders on top of the WebView at the element's rect.
+     *  - The `HTMLElement`/selector is resolved and stripped in the JS layer; it
+     *    never crosses the native bridge.
+     */
+    containerElement?: string | HTMLElement;
+    /**
+     * Low-level escape hatch: explicit bounds (CSS px, viewport-relative) for the
+     * native bar. Normally you pass `containerElement` and the plugin computes
+     * this for you. The JS binding layer populates this field before the call
+     * reaches native; set it directly only if you manage measurement yourself.
+     */
+    bounds?: TabBarBounds;
+}
+/**
+ * Rect (CSS px, viewport-relative — i.e. straight from
+ * `Element.getBoundingClientRect()`) used to position the native tab bar when
+ * bound to an HTML element. In a Capacitor WKWebView, CSS px map 1:1 to UIKit
+ * points, so no devicePixelRatio scaling is applied.
+ */
+export interface TabBarBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SetTabBarBoundsOptions {
+    bounds: TabBarBounds;
 }
 export interface SetSelectedTabOptions {
     /** Either pass numeric index or the item id. */
@@ -89,6 +130,13 @@ export interface LiquidGlassPlugin {
     updateTabBadge(options: UpdateTabBadgeOptions): Promise<void>;
     /** Current layout of the tab bar (height + safe area). */
     getTabBarLayout(): Promise<TabBarLayoutEvent>;
+    /**
+     * Low-level: reposition the native tab bar to an explicit rect (CSS px,
+     * viewport-relative). Driven automatically by the JS binding layer when
+     * `showTabBar` was called with `containerElement`; call it directly only if
+     * you manage element measurement yourself. No-op if the bar is not shown.
+     */
+    setTabBarBounds(options: SetTabBarBoundsOptions): Promise<void>;
     /** Emitted every time the user taps a tab. */
     addListener(eventName: 'tabSelected', listenerFunc: (event: TabSelectedEvent) => void): Promise<PluginListenerHandle>;
     /** Emitted when the tab bar's height or safe-area changes (rotation, etc.). */

package/dist/esm/index.d.ts

@@ -1,4 +1,9 @@
 import type { LiquidGlassPlugin } from './definitions';
+/**
+ * Public plugin façade. Everything delegates straight to the native bridge
+ * except `showTabBar`/`hideTabBar`, which route through {@link TabBarBinder} so
+ * the optional `containerElement` binding works without any consumer wiring.
+ */
 declare const LiquidGlass: LiquidGlassPlugin;
 export * from './definitions';
 export { LiquidGlass };

package/dist/esm/index.js

@@ -1,6 +1,35 @@
-import { registerPlugin } from '@capacitor/core';
-const LiquidGlass = registerPlugin('LiquidGlass', {
+import { Capacitor, registerPlugin } from '@capacitor/core';
+import { TabBarBinder } from './tab-bar-binder';
+const native = registerPlugin('LiquidGlass', {
     web: () => import('./web').then((m) => new m.LiquidGlassWeb()),
 });
+/**
+ * Drives the HTML-element binding lifecycle (measure + observe) on top of the
+ * native bridge. When `showTabBar` is called without `containerElement` it is a
+ * transparent pass-through, so existing callers behave exactly as before.
+ */
+const binder = new TabBarBinder(native);
+/**
+ * Public plugin façade. Everything delegates straight to the native bridge
+ * except `showTabBar`/`hideTabBar`, which route through {@link TabBarBinder} so
+ * the optional `containerElement` binding works without any consumer wiring.
+ */
+const LiquidGlass = {
+    showTabBar: (options) => binder.showTabBar(options),
+    hideTabBar: () => binder.hideTabBar(),
+    // iOS-only: the native method only exists on iOS. On Android the bridge would
+    // throw "not implemented"; resolve quietly instead (the binding layer already
+    // gates on getPlatform() === 'ios', this guards direct low-level callers).
+    setTabBarBounds: (options) => Capacitor.getPlatform() === 'ios' ? native.setTabBarBounds(options) : Promise.resolve(),
+    setSelectedTab: (options) => native.setSelectedTab(options),
+    updateTabBadge: (options) => native.updateTabBadge(options),
+    getTabBarLayout: () => native.getTabBarLayout(),
+    showSearchBar: (options) => native.showSearchBar(options),
+    hideSearchBar: () => native.hideSearchBar(),
+    clearSearchText: () => native.clearSearchText(),
+    // Preserve the overloaded signature for consumers (the bind keeps `this`).
+    addListener: native.addListener.bind(native),
+    removeAllListeners: () => native.removeAllListeners(),
+};
 export * from './definitions';
 export { LiquidGlass };