React Native: Navigating Platform-Specific Shadow Styles

Why it exists

React Native's goal is to write one codebase for two different operating systems, iOS and Android. However, these OSes have fundamentally different native APIs for rendering UI, like how shadows are drawn. React Native must expose these differences to give developers full control, leading to multiple APIs for the same visual effect.

The mental model

Think of React Native's shadow props as a choice between a general-purpose tool and a specialized one. The boxShadow prop is like a web-standard screwdriver that works on most screws (iOS and Android). The classic shadow* props (shadowColor, shadowOffset, etc.) are like a set of platform-specific wrenches; they map directly to the native iOS or Android APIs, offering precise control but requiring you to know which tool works on which platform.

How it works

React Native provides three main ways to create shadows. First, boxShadow is a standalone style prop that implements the web's CSS standard and works on both iOS and Android. Second, dropShadow is an Android-only filter function that casts a shadow based on an element's non-transparent pixels. Third, the classic shadow* props map directly to native platform APIs. Of these, only shadowColor works on both platforms (and only on Android API 28+). The others, shadowOffset, shadowOpacity, and shadowRadius, are iOS-only.

When to use it

Use boxShadow when you need a capable, cross-platform shadow and want behavior similar to web CSS. Use the classic shadow* props when you need a simple shadow and want to align directly with the platform's native rendering, especially on iOS. For Android-specific effects where the shadow should conform to the content's shape (not its bounding box), dropShadow is the tool. For simple elevation on older Android versions, the elevation prop is a fallback.

When not to use it

Do not use the iOS-only shadow* props (shadowOffset, shadowOpacity, shadowRadius) and expect them to work on Android. This is the most common mistake. If you need a consistent shadow on both platforms, boxShadow is a safer starting point than trying to reconcile the platform-specific props. Avoid dropShadow if you need your code to work on iOS.

One canonical example

A common scenario is styling a card component. An engineer might apply shadowColor, shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.25, and shadowRadius: 3.84 to a View. On an iOS device, this produces a soft, subtle drop shadow. On an Android device, these styles will be ignored (except shadowColor on newer APIs), and the card will appear flat, creating a jarring visual inconsistency between the two app versions. This highlights the need for platform-aware styling.