@callstack/liquid-glass

To run the app on iOS, you must first ensure CocoaPods dependencies are installed.

1. Install CocoaPods via Ruby bundler (first time only): bundle install
2. Install native dependencies: bundle exec pod install
3. Run the app: npm run ios or yarn ios.

# Install CocoaPods (if first time)
bundle install

# Update native dependencies
bundle exec pod install

# Run the app using npm
npm run ios

# OR using Yarn
yarn ios

To ensure text remains readable against the glass effect, use PlatformColor from react-native to adapt the text color to the background material.

Limitation: Automatic text color adaptation may fail if the glass view height is $\ge 65$.

import { PlatformColor } from 'react-native';
import { LiquidGlassView } from '@callstack/liquid-glass';

function MyComponent() {
  return (
    <LiquidGlassView style={{ padding: 20, borderRadius: 20 }}>
      <Text style={{ color: PlatformColor('labelColor') }}>Hello World</Text>
    </LiquidGlassView>
  );
}

With Metro running, use the following command to build and launch the application on an Android emulator or connected device.

# Using npm
npm run android

# OR using Yarn
yarn android

Install the library using npm or yarn.

Requirements & Constraints:

• Xcode: Must be compiled with Xcode >= 26.
• React Native: Version 0.80+ is required.
• Expo: This library is not supported in Expo Go.

npm install @callstack/liquid-glass
# or
yarn add @callstack/liquid-glass

If you need to perform a full reload to reset the app state, use the following platform-specific shortcuts:

• Android: Press the <kbd>R</kbd> key twice or select "Reload" from the Dev Menu (<kbd>Ctrl</kbd> + <kbd>M</kbd> on Windows/Linux, <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> on macOS).
• iOS: Press <kbd>R</kbd> in the iOS Simulator.

Before building the app, you must start Metro, the JavaScript build tool for React Native. Run the start command from the root of the project.

# Using npm
npm start

# OR using Yarn
yarn start

Use LiquidGlassView to apply the iOS 26 liquid glass visual effect to a component.

Fallback Behavior: On unsupported iOS versions (below iOS 26), it will render as a normal View without any effects. It is recommended to use isLiquidGlassSupported to provide fallback UI (e.g., a semi-transparent background) for older devices.

import {
  LiquidGlassView,
  LiquidGlassContainerView,
  isLiquidGlassSupported,
} from '@callstack/liquid-glass';

function MyComponent() {
  return (
    <LiquidGlassView
      style=[
        { width: 200, height: 100, borderRadius: 20 },
        !isLiquidGlassSupported && { backgroundColor: 'rgba(255,255,255,0.5)' },
      ]}
      interactive
      effect="clear"
    >
      <Text>Hello World</Text>
    </LiquidGlassView>
  );
}

Use LiquidGlassContainerView to group multiple LiquidGlassView components. When child elements are within the specified spacing distance, their glass effects merge into a single combined effect.

import {
  LiquidGlassView,
  LiquidGlassContainerView,
} from '@callstack/liquid-glass';

function MergingGlassElements() {
  return (
    <LiquidGlassContainerView spacing={20}>
      <LiquidGlassView style={{ width: 100, height: 100, borderRadius: 50 }} />
      <LiquidGlassView style={{ width: 100, height: 100, borderRadius: 50 }} />
    </LiquidGlassContainerView>
  );
}

The isLiquidGlassSupported constant is a boolean that indicates whether the current device supports the liquid glass effect.

import { isLiquidGlassSupported } from '@callstack/liquid-glass';

if (isLiquidGlassSupported) {
  // Device supports liquid glass effect
} else {
  // Provide fallback UI
}

When integrating native modules in a React Native project, you can use react-native.config.js to manage how dependencies and project-specific settings are handled.

For iOS, you can enable automaticPodsInstallation within the project.ios object to automate the installation of CocoaPods.

For autolinked dependencies, you can specify a root directory and define supported platforms. Note that for certain Codegen scripts, you may need to explicitly define a platform (e.g., ios: {}) even if it is an empty object to prevent failures.

const path = require('path');
const pkg = require('../package.json');

module.exports = {
  project: {
    ios: {
      automaticPodsInstallation: true,
    },
  },
  dependencies: {
    [pkg.name]: {
      root: path.join(__dirname, '..'),
      platforms: {
        ios: {},
      },
    },
  },
};