[YevheniiKotyrlo]

Problem

React Native declares its own optional props as ?: T | undefined, while the props this package adds are bare ?: string. Under exactOptionalPropertyTypes the two differ, and the difference falls on the most ordinary thing a consumer writes:

<View className={condition ? "p-4" : undefined} />

error TS2769: No overload matches this call.
  Overload 1 of 2, '(props: ViewProps): View', gave the following error.
    Type '{ className: string | undefined; }' is not assignable to type 'Readonly<ViewProps>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.

styled() has the same bare members: the className its unmapped overload adds, passThrough, and a mapping's nativeStyleMapping; so do the options a consumer writes for the compiler, Metro, the jest helper, the Babel plugin and useNativeCss. A consumer's own declaration that widens such a prop takes effect only when it comes before this package's in the program.

A mapping entry left undefined is also a runtime error: mappingToConfig keeps it, and nativeStyleMapping calls path.split(".") on it:

const StyledView = styled(View, {
  className: {
    target: "style",
    nativeStyleMapping: { color: "accessibilityLabel", backgroundColor: undefined },
  },
});

// .subject { color: blue; background-color: red; }
// The render throws "Cannot read properties of undefined (reading 'split')",
// and the render React retries has no backgroundColor.
<StyledView className="subject" />;

Solution

• Every optional member of types.d.ts and runtime.types.ts, and of the compiler's, Metro's, the jest helper's, the Babel plugin's and useNativeCss's options, takes | undefined, as React Native writes its own, except InlineStyleRecord's s?: never, which marks a key that must stay absent.
• The props a styled() mapping adds come from one StyledSourceProps type, which StyledProps, StyledReactElement and StyledComponent use, and which the unmapped overload uses with DefaultStyledConfiguration, the default mapping src/native/api.tsx and src/web/api.tsx both pass. They stay writable, as the component's own props are.
• A mapping's keys are the style keys the compiler collects: React Native's, which an editor completes, or the camel-cased name of a -rn- declaration, so any string is a key. The type no longer resolves the mapping's target, and an entry may be left undefined, which mappingToConfig drops.

Tests

• src/__tests__/types/optional-members.test.ts walks both declaration files and the option types with the type checker, the flag on, and fails on any optional member that rejects undefined: a property, a class property, a method, a tuple element, a mapped type over keyof T or a K extends keyof T, even behind an alias, and a library type such as Partial that adds ?, in an alias, an extends clause or over a type parameter. Its fixture holds each form, beside an alias, void, an indexed access and a mapped type that keeps each member's own type, which pass. Against main it reports 40 members; here none.
• src/__tests__/types/styled.test.ts compiles mappings through the type checker: any style key, a -rn- declaration's among them, is accepted, a value naming no prop is rejected, the editor completes React Native's style keys whatever the target, and the class props stay writable. Three of its cases fail on main.
• src/__tests__/native/styled.test.ios.tsx: a mapping entry set to undefined maps nothing. On main the case fails tsc, and its render throws.

Verification

Every ci.yml job passes on this head merged into main with #477's harness fix: lint, typecheck, the tests (1350 passed), both builds, the web export, nothing unstaged, commitlint, and the iOS dev build on macOS 27.0.1 with Xcode 27.0, where CI pins 26.6.

A styled() mapping now costs the type checker about 8,100 instantiations against 35,200 on main, and tsc --noEmit over this repository makes 929,290 type instantiations against 979,442. The runs, and the snippet above on main and on this branch, are in this comment.

Known limits

• A misspelled mapping key compiles, since a -rn- declaration can add any key to the style.
• styled() over Reanimated's animated components still exceeds the type checker's depth (TS2589, TS2590), as on main, at about 15% fewer instantiations.
• The package's own code has 17 errors under the flag, in eight files, as on main.

Merge order

• fix(native): answer :dir() per element, and compile every spelling of it #459 adds dir?: "ltr" | "rtl" to ViewProps and TextProps. Whichever lands second widens it, and this test fails until it does.

[YevheniiKotyrlo]

Device evidence — before / after

UNFIXED — The same image. A type declaration has no compiled twin; the evidence is that this story COMPILES, which it cannot against stock types.

FIXED — Each explicit-undefined slot is empty exactly like the omitted-prop slot beside it, and the resolved slot is filled.

before — 3.1.0-rc.0	after — with this PR

Apart from the typeface, the two frames are the same image: an explicit undefined renders as an omitted prop does on both, and only the types tell them apart.

Android 16 emulator (API 36, GLES on the host GPU), 1140×2400 @ 480dpi, both frames from one run. before is the published 3.1.0-rc.0 plus what my test app needs from my other patches to run: the native and native-internal subpath exports, PR 459, cascade-layer ranking, and a shim that compiles a class-qualified :root inert. after adds the rest of my open PRs, this one included. One of them shows on every screen: PR 417 narrows a var()-valued font-family to one family, so the after sets its text in the theme's face where the before falls back to the platform's.

A mapping entry left undefined — main against this PR

The snippet from the body, rendered through the repo's jest with a window.dispatchEvent stub, so React's report of the error it recovered from reaches console.error:

	errors	accessibilityLabel	style
main (eda2b286)	There was an error during concurrent rendering but React was able to recover by instead synchronously rendering the entire root., caused by Cannot read properties of undefined (reading 'split')	#00f	{}
this PR	none	#00f	{ backgroundColor: "#f00" }

Type-check cost — main against this PR

tsc --noEmit --extendedDiagnostics; the counts are the same on every run.

	main (eda2b286)	this PR
this repository: types	167,952	169,592
this repository: instantiations	979,442	929,290
this repository: check time, three runs a side, alternating	3.07–3.80 s	3.03–3.64 s
a file importing styled: instantiations	480,167	479,900
the same file with 13 styled() mappings over React Native's components: instantiations	937,533	585,765
each mapping, on average	35,182	8,143
three styled() mappings over Reanimated's Animated.View, Animated.Text and Animated.ScrollView: instantiations	23,018,446	19,619,557
the same file: check time, and errors	217.5 s; 2 × TS2589, 1 × TS2590	204.3 s; the same errors
The mapping type no longer resolves its target: its keys are React Native's style keys, which an editor completes, beside any string.

Windows 11 Pro 10.0.26200, AMD Ryzen 9 9950X3D, Node 26.8.1, TypeScript 6.0.3.