Liquid Glass Screens: React Native Expo Welcome Screens

Description:

Liquid Glass Screens is a React Native and Expo cookbook that demonstrates two gesture-driven welcome screens with Skia shaders, floating stickers, and swipe-up motion.

Cookbook 1 uses a cloud video backdrop, and Cookbook 2 uses a star layer with a horizon glow.

Preview

Features

• Two cookbook components: SkyGlassWelcome and AstroGlassWelcome.
• Skia Canvas layers for the scene, stickers, lens, glass, and copy.
• UI-thread worklets for gestures, shader uniforms, sticker physics, and dust.
• initialState="gate" and initialState="open" preview states.
• Typed semantic actions such as sky.lets-go and astro.lets-go.
• Asset-generation prompts for wordmarks, stickers, backdrops, and other artwork.

How To Use It

Run the Expo gallery

The gallery needs Node.js 22.13 or newer, Xcode for iOS, or Android Studio for Android. React Native Skia runtime shaders and video decoding require a development build or a native build. Expo Go cannot load these screens.

git clone https://github.com/Appllama/liquid-glass-screens.git
cd liquid-glass-screens
npm ci
npm run ios

The default route is the gallery home. The two direct routes are /sky and /astro. The iOS URI examples below open Cookbook 2 or start Cookbook 1 in its open state:

npx uri-scheme open "liquid-glass://astro" --ios
npx uri-scheme open "liquid-glass://sky?state=open" --ios

Render one cookbook

Wrap the selected screen in a full-height React Native surface inside a GestureHandlerRootView. Preload its bitmaps and clip before mounting the animated React tree.

Copy only the selected component, its theme, its assets, and the helpers it imports. Keep glass.ts, orb-field.tsx, copy.tsx, and types.ts when the selected cookbook uses the shared helper set.

import { AstroGlassWelcome, type LiquidGlassActionId } from "./src/liquid-glass";
function handleAction(actionId: LiquidGlassActionId) {
  if (actionId === "astro.lets-go") {
    // Navigate to the app's onboarding route.
  }
}
export function Welcome() {
  return <AstroGlassWelcome onActionPress={handleAction} />;
}

Install the source-distributed entry

Use the source-distributed src/index.ts entry in an SDK-matched workspace:

npm install github:Appllama/liquid-glass-screens

import { SkyGlassWelcome } from "liquid-glass-screens";
export function SkyWelcome() {
  return <SkyGlassWelcome onPrimaryPress={() => {}} />;
}

Select a cookbook from the registry

Use CookbookScreen when the host app stores the screen name as typed data:

import { CookbookScreen, type CookbookId } from "./src/liquid-glass";
export function Preview({ name }: { name: CookbookId }) {
  return (
    <CookbookScreen
      name={name}
      initialState="open"
      onActionPress={(actionId) => console.log(actionId)}
    />
  );
}

Create a product-specific theme

LiquidGlassScreen accepts a theme object. Replace the supplied wordmark and copy before using the screen in a product flow:

import { LiquidGlassScreen, SKY_THEME } from "./src/liquid-glass";
const MY_THEME = {
  ...SKY_THEME,
  id: "sky" as const,
  wordmark: require("./assets/my-wordmark.png"),
  copy: {
    ...SKY_THEME.copy,
    headline: "Plan and share",
    struck: "spreadsheets",
    kept: "trips",
  },
};
export function ProductWelcome() {
  return <LiquidGlassScreen theme={MY_THEME} onPrimaryPress={() => {}} />;
}

API reference

Project structure and customization

Use these paths when copying one cookbook into an app:

assets/cookbooks/sky/       cloud loop, poster, wordmark, stickers
assets/cookbooks/astro/     star layer, glow layer, wordmark, stickers
docs/MOTION_SPEC.md         measured geometry, thresholds, springs, physics
docs/ASSET_PROVENANCE.md    generated-asset inventory
prompts/                    prompts for each cookbook's assets
src/app/                    Expo Router gallery and routes
src/liquid-glass/           screen, shaders, sticker field, copy, themes
src/index.ts                source-distributed package entry

Motion, verification, and platform limits

The reference geometry is authored at 402 by 874 points and scales with the device surface. Gesture values, shader uniforms, sticker physics, and dust run in worklets. The JavaScript thread receives the open-state transition and semantic action.

Reduced motion removes the landing bounce and changes the rotating third-line transition to a fade. The component also controls the status bar style for each backdrop and exposes the swipe hint as an accessibility label.

Run the verification command in a native or development build:

npm run verify

The command runs TypeScript, Expo ESLint, dependency compatibility tests, and particle worklet regressions. The project has no web export. Its screens depend on Skia runtime shaders and native video decoding.

FAQs

Q: Can I use only the Sky or Astro screen?

A: Yes. Import SkyGlassWelcome or AstroGlassWelcome, then copy the selected theme, its assets, and the helpers it imports. The Expo Router gallery is optional.

Q: How does the welcome screen notify the host app?

A: Pass onActionPress. The handler receives a typed semantic ID such as sky.lets-go or astro.lets-go, which the app can map to its existing onboarding route.

Q: Which Expo versions does the demo target?

A: The demo targets Expo SDK 57, React Native 0.86, React Native Skia 2.6, and Reanimated 4.5. Review native dependency versions before consuming the source in an app on another SDK.

Q: Can I ship the included artwork in a product?

A: The project requires identity and artwork changes before public or commercial use. Replace the wordmarks, stickers, copy, and backdrops, create an original composition and motion language, and review the asset provenance notice.