masked-view

@react-native-masked-view/masked-view is a cross-platform React Native component that renders a child view masked by the alpha channel of another React element. Pass any element as maskElement and MaskedView uses it as a stencil: fully opaque pixels reveal the content behind them, fully transparent pixels hide it, and partially transparent pixels blend the two, enabling gradient fades, text cutouts, and custom-shaped reveals without per-platform clipping hacks.

The library ships true native implementations for iOS (UIView mask layering via didUpdateReactSubviews/displayLayer) and Android (Canvas bitmap compositing via PorterDuffXfermode in dispatchDraw, with an androidRenderingMode prop to trade performance for animated-mask correctness), plus a web fallback that snapshots the mask subtree to a PNG using modern-screenshot and applies it as a CSS mask. Originally extracted from React Native core as part of the ‘Lean Core’ initiative, it has since become the de facto MaskedView used across the React Native and Expo ecosystem, though the repo itself now sees only occasional maintenance.

What You Get

• A single <MaskedView> component accepting a maskElement prop plus standard View props, usable as a drop-in on iOS, Android, and Web.
• Native implementations tuned per platform: PorterDuffXfermode bitmap compositing on Android, UIView mask layering on iOS, and a modern-screenshot-based DOM snapshot mask on web.
• An androidRenderingMode prop (hardware/software) to control whether animated mask elements redraw correctly on Android.
• TypeScript (types/index.d.ts) and Flow type definitions for the component API.
• An example React Native app demonstrating basic masked-view usage patterns.

Common Use Cases

• Fading list/carousel edges with a gradient mask element.
• Text-cutout reveal effects where a bold headline masks a photo or gradient behind it.
• Animated onboarding/splash transitions using a shape or logo as the mask.
• Custom-shaped avatars, icons, and badges without per-platform clip-path or corner-radius workarounds.

Under The Hood

Architecture The library is a thin, platform-branching wrapper: index.js re-exports a single MaskedView component whose implementation differs per target. On native platforms (js/MaskedView.js), it’s a class component that validates maskElement is a real React element, then renders a native host component (requireNativeComponent('RNCMaskedView')) wrapping an absolutely-positioned, pointer-events-none View holding the mask element followed by the actual children — the native view manager on each platform (RNCMaskedViewManager.m on iOS, RNCMaskedViewManager.java on Android) is responsible for treating the first native subview as the mask and compositing it against the rest. The web variant (js/MaskedView.web.js) takes a completely different approach: it renders the mask element off-screen, uses a ResizeObserver plus modern-screenshot’s domToPng to rasterize it into a data URL, and applies that as a CSS mask on the visible container — a hooks-based function component rather than a class, reflecting its separate maintenance path from the native code.

Tech Stack The JS layer targets React >=16 and React Native >=0.57 as peer dependencies, written with Flow annotations on the native side and plain modern JS/TS on the web side, with a types/index.d.ts file supplying TypeScript typings independently. Native code is Java (Android, targeting ReactViewGroup/SimpleViewManager from the React Native Android runtime) and Objective-C (iOS, subclassing RCTView). Tooling includes ESLint (@react-native/eslint-config), Prettier, Flow (flow-bin), and TypeScript’s tsc -noEmit for type checking, wired into a GitHub Actions CI workflow (.github/workflows/ci.yml). The web mask rendering depends on the external modern-screenshot package, which consumers must install separately.

Code Quality There are no automated unit or integration tests in the repository — package.json’s test:js script is a no-op (echo 0), and the real quality gates are static: ESLint, Prettier formatting, Flow type checking, and tsc -noEmit, all run in CI. Error handling is minimal by necessity (this is a rendering-focused UI primitive): the native MaskedView.js component guards against an invalid maskElement with a one-time console warning and a graceful fallback to rendering an unmasked View. Naming and file organization are conventional for a React Native native-module package (js/, android/, ios/, types/), and the Android/iOS native code is compact, single-purpose, and easy to audit.

What Makes It Unique Rather than emulating masking with opacity tricks or SVG clip-paths, it does real alpha-channel compositing natively — PorterDuffXfermode(DST_IN) bitmap blending on Android and native UIView mask layering on iOS — giving pixel-accurate masks including anti-aliased edges and animatable mask content (via the software rendering mode escape hatch for Android’s hardware-layer limitation). The web implementation takes a pragmatic, unusual approach for a masking primitive: rather than trying to replicate native compositing in the DOM, it snapshots the mask subtree to a PNG image and lets the browser’s native CSS mask property do the compositing, trading a small runtime snapshot cost for correctness across arbitrary DOM mask content.