7 minute read

Liquid Glass

Liquid Glass is a dynamic system material used in the interface layer to reveal what’s underneath without hiding it, providing separation and hierarchy through glass-like optical properties (primarily reflection and refraction) while adapting to context and interaction. Its goal is to unify the visual language across platforms while keeping the focus on your content.

It doesn’t “paint” a fixed background: it modulates the light of the underlying content, produces lensing (perceptible refraction/curvature of the background image), and reacts to touch, pointer, and device motion—adding depth without blocking what’s beneath.

In Apple’s words, it’s a translucent material that “reflects and refracts its surroundings” and “transforms dynamically to direct attention,” applied to controls, navigation, icons, and widgets.

What “bend and concentrate light” means

Apple uses “physical” language because Liquid Glass simulates real optics so you perceive shape, elevation, and hierarchy without opaque boxes:

  1. Bending light = refraction (lensing). The material slightly deflects the background image (like real glass), making the element’s silhouette and elevationvisible while keeping the content present.

  2. Concentrating light = highlights and shadows. The system modulates highlights and shadows; that “concentration” guides attention and defines volume without hiding the background.

In one sentence: Liquid Glass refracts and reflects the environment to create visible depth and hierarchy, always showing the content and adapting in real time.

How to think about Liquid Glass

Picture two planes:

  1. Content (your app: lists, images, maps…).
  2. An interface layer that “floats” above with Liquid Glass, showing what’s underneath with glass properties (lensing, perceived thickness, reflections, and shadows) and built-in kinetics so it feels organic and alive. The system prioritizes continuity (it doesn’t “cut” the background) and legibility, adjusting tint, shadowing, and dynamic range as context changes.

Controls and bars also elevate their presence; scroll edge effects mark the content–UI boundary with a subtle blur: use .soft by default (iOS/iPadOS) and .hard when you need a more opaque boundary (macOS, dense headers). Apply a single edge effect per view.

What problem does it solve?

  • Hierarchy without opaque boxes. The layer for controls and navigation floats over the content, preserving visual continuity and ensuring contrast.
  • Cross-platform cohesion. The same rules for material, shape, and grouping on iPhone, iPad, Mac, watchOS, tvOS, and visionOS.
  • Less decoration; more structure. Apple recommends removing extra backgrounds and borders and relying on the material + edge effects and grouping to express hierarchy.

Essential material properties

  • Lensing: background curvature reveals an element’s shape and elevation without blocking it.
  • Continuous adaptability: the material can change its appearance (e.g., light/dark on small elements; greater perceived “thickness” on large surfaces) to maintain legibility.
  • Interactive response: inner glow, subtle flex/elasticity, and tactile/gesture coherence.

Official variants and correct usage

There are two visual variants:

  • Regular. Versatile; includes adaptive behaviors and works at any size and on any background. Use it for navigation and structural surfaces.
  • Clear. More transparent and with fewer adaptive layers; when it disrupts flow, add dimming to the underlying content to preserve legibility. Do not mix Regular and Clear in the same context.

Technical note (SwiftUI): There is Glass.identity, which does not apply Liquid Glass (effect disabled). It’s useful for state-based or accessibility control without rewriting your view, but it is not a material style.

Design best practices

  • Avoid “glass on glass” and group nearby elements. Glass should read as a single surface, not stacked layers. If you have multiple glassy controls close together (chips, buttons, tags…), wrap them in GlassEffectContainer to share sampling and form one geometry that morphs correctly between states. If they will transition between layouts, bind the union with glassEffectUnion(id:namespace:) to preserve material continuity.
  • Color with intent. The tint produces a range of tones mapped to background brightness (like real colored glass): reserve it for primary actions and avoid tinting everything.
  • Edge effects (official guidance). Use .soft by default (iOS/iPadOS) and .hard in dense contexts (common on macOS). Apply one edge effect per view.
  • Technical note — modifier order. Apply glassEffect after modifiers that alter shape/space (padding, background, mask, clipShape) so sampling and glass geometry are correct.

Widgets and Liquid Glass

On iPhone, iPad, Mac, and Apple Watch, widgets use Liquid Glass and can appear in tinted (accented) or clear modes. In accented rendering, the system may tint content and replace the background with themed glass or an accent color to ensure legibility and thematic coherence. Review the WidgetKit guide to optimize contrast in each mode.

How to start adopting

  1. Remove extra backgrounds/borders from bars and containers; let the system determine the background.
  2. Start with Regular on structural surfaces; use Clear only if you also add dimming and the content above is “strong” (high-weight symbols/labels).
  3. When you have multiple glass elements together, wrap them in GlassEffectContainer and add glassEffectUnion(id:namespace:), glassEffectID, or glassEffectTransition if they’ll morph between states (better performance and consistency).

How it “looks” and how it’s composed (from code)

You have two complementary approaches:

  1. Glass background (surface). Add a 3D material background with thickness, specularity, blur, and shadows: glassBackgroundEffect(in:displayMode:). Useful when the container itself “is glass.”
  2. Glass effect on the element. Apply the effect and its shape (e.g., capsule) directly to the control or content: glassEffect(_:in:). Group nearby elements with GlassEffectContainer.

Modifier order. Apply glassEffect after modifiers that alter shape/space (padding, background, mask, clipShape) so sampling and glass geometry are correct.

Adoption note: if you use standard components (SwiftUI/UIKit/AppKit), much of the look arrives automatically; first remove extra backgrounds and let the material and edge effects do the work.

Accessibility

  • Reduce Transparency: glass becomes “frostier,” obscuring more of the background.
  • Increase Contrast: elements become more neutral with highlight borders.
  • Reduce Motion: elasticity and motion are toned down.

These adaptations apply to Liquid Glass automatically when the person enables system accessibility settings.

Icons and Icon Composer

Icon Composer is Apple’s official app for building Liquid Glass-powered layered icons from a single design. It lets you tune material properties, preview with dynamic lighting, and annotate how your icon should look in different rendering modes (Default, Dark, and Monochrome). It’s integrated with Xcode, and you can also export static assets for the App Store/marketing.

To use it in your project, add the .icon file to the target and select it in App Icons and Launch Screen; the .icon becomes that target’s App Icon.

What changes in the icon language

  • Unified cross-platform design. Icon Composer starts from a single design you can adapt to iPhone, iPad, Mac, and Apple Watch; Apple provides more rounded enclosures and an updated grid that help maintain consistency across platforms.
  • Living material. The icon “comes alive” with Liquid Glass properties that respond to lighting; you don’t need to “paint” heavy highlights or bevels into your base art because the material generates them coherently. (See also the session Say hello to the new look of app icons for design principles.)
  1. Prepare layered artwork in your editor (background + 1..n foreground layers). Keep vectors whenever possible for crispness at all sizes.
  2. Open Icon Composer from Xcode: Xcode ▸ Open Developer Tool ▸ Icon Composer (or download the app from Apple’s site).
  3. Import and compose. Organize layers and tune the material (specular highlights, blur, translucency, shadows). Preview with dynamic lighting and at various sizes/backgrounds.
  4. Annotate appearances. Define looks for Default, Dark, and Monochrome within the same file to optimize legibility in each mode.
  5. Integrate in Xcode. Add the .icon file to your project and select it in App Icons and Launch Screen to use it as the target’s App Icon. (The new file type integrates directly with Xcode; you don’t have to maintain multiple variants in the asset catalog.)
  6. Export static assets when you need communication materials (App Store, web, presentations).

Drawing guidelines (Do / Don’t)

Do:

  • Clean layering (one background + foreground planes); let Liquid Glass provide depth and highlights.
  • Simplicity and frontality: clear, legible shapes at small sizes; avoid details that compete with the material. (Reinforced in the WWDC25 icon sessions.)
  • Gradients and color with intent: use system gradients or controlled palettes that harmonize with lighting; reserve color for emphasis. (Professional judgment based on HIG + sessions.)

Don’t:

  • Paint heavy shadows/bevels in the base art (the material already provides highlights and volume).
  • Manually export multiple variants per platform/mode if you work with Icon Composer: its single file centralizes appearances and sizes.

Quick checklist before you ship

  • The icon reads well in Default, Dark, and Monochrome (without losing contrast).
  • The base art doesn’t compete with the material (no redundant highlights/bevels).
  • Xcode checks: the .icon is assigned in App Icons and Launch Screen and looks correct on all target devices.
  • Static assets exported for App Store/marketing.

Meta

Updated: