UniversalGlass

Use UniversalGlassEffectContainer to group multiple glass-effected views. This allows for advanced grouping behaviors like unioning effects. To link views within a container, use .universalGlassEffectUnion(id:namespace:) with a shared ID and a @Namespace.

@Namespace private var ns

UniversalGlassEffectContainer {
    HStack {
        AvatarView()
            .universalGlassEffect()
            .universalGlassEffectUnion(id: "profile", namespace: ns)

        DetailsView()
            .universalGlassEffect()
            .universalGlassEffectUnion(id: "profile", namespace: ns)
    }
}

Decide whether to use the backport target based on your development needs:

Use the Backport Target if:

• You want to use Apple's glass syntax now without wrapping every call site in #if availability checks.
• You are maintaining codebases that already use Apple's glass syntax but need to compile against pre-OS 26 SDKs.
• You are building shared components that must compile on Xcode 15+ while exposing a future-facing API surface.

Omit the Backport Target if:

• You prefer to use the explicit universal prefixes (e.g., universalGlassEffect) directly. The core UniversalGlass module works on all supported OS versions without the backport layer.

To create a single cohesive glass slab that merges multiple neighboring elements, use grouping and union helpers. On OS 26+, these forward to SwiftUI. On earlier systems, they use glassEffectParticipantContext to allow a fallback container to merge participants into a single visual unit.

// Grouping helpers
View.universalGlassEffectUnion(id:namespace:rendering:)
View.universalGlassEffectID(_:in:rendering:)

UniversalGlass uses runtime availability checks to determine if the device supports native OS 26 glass APIs.

• On OS 26+: It transparently routes calls to the native SwiftUI glass implementations.
• On earlier OS versions: It uses a fallback renderer that registers effects as participants via anchor preferences, groups views by union keys/IDs, and draws composite material overlays that respect shapes and transitions.

Known Limitation: On pre-OS 26 systems, the fallback container ignores the spacing parameter.

UniversalGlass styles are standard PrimitiveButtonStyle implementations, making them fully compatible with existing SwiftUI patterns:

• Modifier Layering: You can layer standard modifiers like .controlSize, .tint, and .font directly onto the button.
• Coexistence: You can use UniversalGlass helpers alongside other system styles like .borderedProminent.
• Debugging: You can opt individual call sites into .material rendering to debug fallback behavior or ensure platform parity.

Add UniversalGlass as a dependency in your Swift Package Manager configuration. You can target the main module for full functionality or include the optional backports module for shorthand syntax.

Targets:

• UniversalGlass: Main module containing glass effects, button styles, and containers.
• UniversalGlassBackports: Optional module providing shorthand APIs like .glass and .glassEffect.

dependencies: [
    .package(url: "https://github.com/Aeastr/UniversalGlass.git", branch: "main")
]

To use Apple-style glass syntax (like .glassProminent) on older SDKs, you must include both the core UniversalGlass package and the UniversalGlassBackports target in your Swift Package Manager configuration. UniversalGlass provides the rendering logic, while UniversalGlassBackports exposes the symbols that mimic Apple's future API names.

// In your Package.swift
.package(url: "https://github.com/Aeastr/UniversalGlass", from: "1.0.0"),

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "UniversalGlass", package: "UniversalGlass"),
        .product(name: "UniversalGlassBackports", package: "UniversalGlass"),
    ]
)

To apply a glass effect to a SwiftUI view, use the .universalGlassEffect() modifier. By default, it provides a regular glass effect. You can chain configuration methods like .tint() to customize the appearance.

import UniversalGlass

Text("Hello")
    .universalGlassEffect(.regular.tint(.purple))

Developers can extend the container's behavior using the following patterns:

• Custom Metadata: Use glassEffectParticipantContext to pass additional metadata. Modifiers should write to the environment before registering their participant.
• Custom Grouping: To introduce new grouping semantics, extend GlassEffectGroupingKey or implement a custom overlay that consumes the participant list.
• Performance Note: When extending, ensure heavy work is avoided in the body. The container is designed to resolve geometry in a single pass for both the mask and background layers; extensions should respect this single-pass approach.

Use UniversalGlassEffectContainer to orchestrate multiple glass effects so they render as a single fused surface.

On OS 26+, it automatically defers to SwiftUI's native GlassEffectContainer. On earlier OS releases, it uses a fallback renderer that groups elements by shared union keys or effect IDs to create a 'melted' single slab effect. This ensures that neighboring elements appear to share a single glass plate while respecting individual shapes and hit-testing.

@Namespace private var ns

UniversalGlassEffectContainer {
    HStack {
        AvatarView()
            .universalGlassEffect()
            .universalGlassEffectUnion(id: "profile", namespace: ns)

        DetailsView()
            .universalGlassEffect()
            .universalGlassEffectUnion(id: "profile", namespace: ns)
    }
}