Expo Liquid Glass

Execution Order

1. Confirm platform/runtime constraints.
2. Check design alignment against HIG buckets (recommended for design-heavy tasks).
3. Pick one primary implementation path (add a second path only if needed).
4. Apply Apple-aligned visual rules before writing code.
5. Implement guarded glass components with explicit fallbacks.
6. Run accessibility and visual QA in both light/dark and clear/tinted appearances.

1) Preflight Constraints

• Use Liquid Glass only for controls/navigation chrome, not primary content surfaces.
• Treat these APIs as fast-moving: check current Expo SDK docs before finalizing syntax.
• Expect a development build for advanced iOS-native features:

  expo-glass-effect

  and

  @expo/ui

  are not reliable in Expo Go on iOS.
• Keep scope on Liquid Glass in Expo: use HIG rules to guide implementation, not to redesign unrelated product behavior.

2) Design Alignment (Recommended for design-heavy tasks)

1. Foundations Check materials, color, layout, motion, and accessibility implications.
2. Patterns Check navigation/search/flow behavior for consistency with system expectations.
3. Components Check bars, buttons, menus, fields, sidebars, and overlays used by the screen.
4. Inputs Check touch, gesture, keyboard, and pointer behavior for parity and discoverability.

references/apple-liquid-glass-design.md

3) Choose the Primary Path

expo-glass-effect

@expo/ui

Host

expo-router/unstable-native-tabs

@callstack/liquid-glass

• Use native tabs for navigation chrome.
• Use

  expo-glass-effect

  for floating controls inside screens.
• Use

  @expo/ui

  only where SwiftUI-specific behavior is required.

4) Apple-Style Design Rules (Critical)

1. Keep hierarchy in layout and spacing, not decorative layers.
2. Group related controls into shared glass clusters; separate unrelated groups with space.
3. Let content run edge-to-edge behind controls so glass has something to refract.
4. Use system controls/material first; customize minimally.
5. Move strong brand color into content/background, not navigation bars.
6. Keep icons/labels high contrast in light, dark, clear, and tinted modes.
7. Avoid full-screen glass sheets; reserve glass for top-level interaction surfaces.

5) Implementation Patterns

Pattern A: Guarded Adaptive Glass Wrapper

import { Platform, View } from 'react-native';
import { BlurView } from 'expo-blur';
import { GlassView, isGlassEffectAPIAvailable } from 'expo-glass-effect';

export function AdaptiveGlass({ style, children }) {
  if (isGlassEffectAPIAvailable()) {
    return (
      <GlassView style={style} glassEffectStyle="regular" tintColor="#FFFFFF10">
        {children}
      </GlassView>
    );
  }

  if (Platform.OS === 'ios') {
    return (
      <BlurView style={style} intensity={40} tint="dark">
        {children}
      </BlurView>
    );
  }

  return <View style={[style, { backgroundColor: 'rgba(60,60,67,0.30)' }]}>{children}</View>;
}

Pattern B: Safe

expo-glass-effect

Usage

• Prefer

  glassEffectStyle

  :

  'regular' | 'clear' | 'identity'

  as needed.
• Never set

  opacity < 1

  on

  GlassView

  or parents.
• Treat

  isInteractive

  as mount-time only. Remount using a

  key

  if it must change.
• Avoid scrollable content inside

  GlassView

  .
• Check availability with

  isGlassEffectAPIAvailable()

  before rendering.

Pattern C: Native Tabs (SDK-Specific Syntax)

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.TabBarIcon
    ios={{ default: 'house', selected: 'house.fill' }}
    androidIconName="home"
  />
  <NativeTabs.Trigger.TabBarLabel>Home</NativeTabs.Trigger.TabBarLabel>
</NativeTabs.Trigger>

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.Icon sf="house.fill" md="home" />
  <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
</NativeTabs.Trigger>

NativeTabs

ThemeProvider

Pattern D: SwiftUI Glass with Namespace IDs

@expo/ui

import { Host, Namespace, Text } from '@expo/ui/swift-ui';
import { glassEffect, glassEffectID, padding } from '@expo/ui/swift-ui/modifiers';

const ns = new Namespace('glass');

<Host style={{ width: 220, height: 56 }}>
  <Text
    modifiers={[
      padding({ all: 16 }),
      glassEffect({ glass: { variant: 'regular' } }),
      glassEffectID({ id: 'primary-chip', in: ns }),
    ]}
  >
    Explore
  </Text>
</Host>;

6) Accessibility and Quality Gates

• Check

  AccessibilityInfo.isReduceTransparencyEnabled()

  and provide non-glass fallback.
• Verify legibility over bright, dark, and high-saturation backgrounds.
• Validate both clear and tinted system appearances on iOS 26.
• Keep hit targets and spacing stable during interactive animations.
• Measure scroll performance with and without glass on low-end test devices.

7) Common Failure Modes and Fixes

• Double blur in headers: Native header blur + custom glass child causes muddy layering. Use a plain translucent View in header accessories.
• Flat-looking glass: Solid backgrounds remove refraction cues. Add tonal variation, gradients, or imagery behind the surface.
• Over-customized controls: Heavy tint/border/shadow stacks reduce native feel. Start from system defaults, then tune lightly.
• Missing runtime guards: Rendering glass APIs unguarded can crash or silently degrade on unsupported builds.
• Version drift: Native-tabs and SwiftUI wrappers evolve quickly; check SDK-specific docs before coding.

8) Reference Loading Strategy

• references/expo-ui-swiftui.md

  : SwiftUI component mapping, Host layout, modifier patterns.

• references/native-tabs.md

  : Native tab behaviors, migration notes, known issues.

• references/callstack-liquid-glass.md

  : Callstack setup and compatibility tradeoffs.

• references/apple-liquid-glass-design.md

  : Apple-aligned composition, hierarchy, motion, and accessibility rules.