---
title: balochcodes/fluidislandhud
framework: Swift Package Catalog
role: article
path: packages/balochcodes/fluidislandhud
---

# balochcodes/fluidislandhud

A fluid, Apple Dynamic Island and floating status HUD banner component for **SwiftUI** featuring organic spring expansions, animated progress bars, semantic notification presets, and interactive swipe-to-dismiss gestures.

## ✨ Features

- 🏝️ **Authentic Dynamic Island Physics:** Smoothly morphs from a compact pill into an expanded card using Apple-grade spring physics. - 🚦 **Semantic Notification Presets:** Instant convenience methods for `.success`, `.error`, `.warning`, `.info`, and `.loading`. - 📊 **Animated Progress Bar:** Real-time percentage indicator and smooth progress track for background sync and downloads. - 👆 **Interactive Gestures:** Tap to expand/collapse and swipe upwards to instantly dismiss. - 📳 **Tactile Haptic Feedback:** Native iOS haptics on banner presentation. - 🎨 **Deep Customization:** Adjust background glass, border tints, typography, corner radii, and spring response via `FluidIslandTheme`. - ⚡ **Zero External Dependencies:** Built 100% on native SwiftUI primitives.

---

## 📦 Installation

### In Xcode (Recommended) 1. Open your project in Xcode and go to **File** ➔ **Add Package Dependencies...** 2. In the search box, paste the repository URL:    ```text    https://github.com/BalochCodes/FluidIslandHUD.git    ``` 3. Select **Up to Next Major Version** (`1.0.0`) and click **Add Package**.

### In `Package.swift` Add `FluidIslandHUD` to your `dependencies`:

```swift dependencies: [     .package(url: "https://github.com/BalochCodes/FluidIslandHUD.git", from: "1.0.0") ] ```

Import the framework:

```swift import SwiftUI import FluidIslandHUD ```

---

## 🚀 Usage Examples

### 1. Simple Setup with One-Liner Toasts

Attach `.fluidIsland()` to your root view, then trigger notifications from anywhere via `FluidIslandManager.shared`:

```swift import SwiftUI import FluidIslandHUD

@main struct MyApp: App {     var body: some Scene {         WindowGroup {             ContentView()                 .fluidIsland() // Injects HUD overlay onto app root         }     } }

struct ContentView: View {     var body: some View {         VStack(spacing: 20) {             Button("Copy Link") {                 FluidIslandManager.shared.showSuccess(                     "Copied to Clipboard",                     subtitle: "Link ready to paste anywhere"                 )             }

Button("Simulate Error") {                 FluidIslandManager.shared.showError(                     "Network Timeout",                     subtitle: "Please check your internet connection"                 )             }         }     } } ```

---

### 2. Live Download / Sync Progress HUD

```swift struct FileSyncView: View {     @State private var downloadProgress: Double = 0.0

var body: some View {         Button("Start File Sync") {             downloadProgress = 0.0                          Timer.scheduledTimer(withTimeInterval: 0.2, repeats: true) { timer in                 downloadProgress += 0.1                                  FluidIslandManager.shared.showProgress(                     "Syncing Assets...",                     progress: downloadProgress                 )

if downloadProgress >= 1.0 {                     timer.invalidate()                     FluidIslandManager.shared.showSuccess("Assets Synced!")                 }             }         }     } } ```

---

### 3. Custom Themed Floating Island

```swift let customTheme = FluidIslandTheme(     backgroundColor: Color(red: 0.1, green: 0.12, blue: 0.18),     borderColor: Color.blue.opacity(0.3),     compactCornerRadius: 28,     expandedCornerRadius: 36,     springResponse: 0.38,     springDamping: 0.68 )

ContentView()     .fluidIsland(theme: customTheme) ```

---

## 🛠️ API Reference

### `FluidIslandManager`

| Method | Parameters | Description | | :--- | :--- | :--- | | `showSuccess()` | `title`, `subtitle?`, `duration = 3.0` | Displays success toast with green checkmark. | | `showError()` | `title`, `subtitle?`, `duration = 3.5` | Displays error alert with red exclamation mark. | | `showWarning()` | `title`, `subtitle?`, `duration = 3.0` | Displays warning notice with yellow triangle. | | `showInfo()` | `title`, `subtitle?`, `duration = 3.0` | Displays information notice with blue icon. | | `showProgress()` | `title`, `progress: Double (0.0-1.0)` | Displays progress HUD with live progress bar. | | `show()` | `IslandItem` | Displays custom configured island model. | | `dismiss()` | — | Animates dismissal of current active island. |

### `FluidIslandTheme`

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `backgroundColor` | `Color` | `Color.black` | Island pill background color. | | `borderColor` | `Color` | `Color.white.opacity(0.12)` | Outer pill stroke border color. | | `compactCornerRadius`| `CGFloat` | `24.0` | Corner radius in compact pill presentation. | | `expandedCornerRadius`| `CGFloat`| `32.0` | Corner radius in expanded card presentation. | | `titleFont` | `Font` | `.rounded.semibold (14)` | Typography font for primary title. | | `subtitleFont` | `Font` | `.rounded.regular (12)` | Typography font for secondary subtitle. | | `springResponse` | `Double` | `0.42` | Duration/response of spring morph animation. | | `springDamping` | `Double` | `0.72` | Damping factor for organic island bounce. | | `enableHaptics` | `Bool` | `true` | Fires tactile vibration on presentation (iOS). |

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Author Created by [Shahzain Baloch](https://github.com/ShahzainBaloch).

## Package Metadata

Repository: balochcodes/fluidislandhud

Default branch: main

README: README.md