feat(CSS): animate backgroundImage gradients on web

[MatiPl01]

Note

This pull request was authored by AI on behalf of @MatiPl01.

Summary

CSS animations and transitions of backgroundImage (native support in #10590) had no web processor, so gradients in keyframes were dropped. This adds a serializer that turns the React Native gradient object form into CSS linear-gradient() / radial-gradient() strings, with the same precedence rules react-native-web applies to a static style (two-axis radial position, px for numeric positions, a circle with two different radii degrades to an ellipse), and removes the experimental_backgroundImage: false exclusion.

Browsers decide how the animation looks: current browsers switch background-image discretely even between gradients of the same structure. A transition needs a string backgroundImage in the base style because react-native-web does not accept the object form there.

Test plan

• Jest: backgroundImage.test.ts (web processor) and animationParser.test.ts.
• Manual: the Background Image example screen in web-example shows the gradient keyframes switching at the midpoint.

Changelog

Entry added to the Unpublished section of packages/react-native-reanimated/CHANGELOG.md.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds web processing for backgroundImage gradient objects. The processor serializes linear and radial gradients, color stops, positions, sizes, multiple gradients, and numeric colors. The web style configuration registers the processor, and tests cover processor output and CSS keyframe serialization. Documentation and the changelog describe web support. The example route is no longer limited to iOS and Android.

Priority: ⬇️ Low

Change: Feature

Merge Risk: 🟡 Moderate · up to fe282

A valid keyframe that clears backgroundImage can throw while CSS is built, preventing the affected web animation from running. Add the null guard before merging.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the web support added for animating and transitioning backgroundImage gradients, including implementation details and tests.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding web support for CSS animation of backgroundImage gradients.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 38a51a50-2993-4371-a42e-6ef6041e46e7

📥 Commits

Reviewing files that changed from the base of the PR and between 1c21b2e and 08579fb.

📒 Files selected for processing (8)

• apps/common-app/src/apps/css/examples/animations/routes/properties/base.ts
• docs/docs-reanimated/docs/guides/supported-properties.mdx
• packages/react-native-reanimated/CHANGELOG.md
• packages/react-native-reanimated/src/common/web/style/config.ts
• packages/react-native-reanimated/src/common/web/style/processors/__tests__/backgroundImage.test.ts
• packages/react-native-reanimated/src/common/web/style/processors/backgroundImage.ts
• packages/react-native-reanimated/src/common/web/style/processors/index.ts
• packages/react-native-reanimated/src/css/web/__tests__/animationParser.test.ts

💤 Files with no reviewable changes (1)

• apps/common-app/src/apps/css/examples/animations/routes/properties/base.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟠 Major · Guard null before iterating. · backgroundImage.ts:166-181

packages/react-native-reanimated/src/common/web/style/processors/backgroundImage.ts:166-181
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Guard null before iterating. A public Reanimated CSS keyframe can contain backgroundImage: null. Keyframe processing passes it to webPropsBuilder, whose createPropsBuilder skips only undefined. processBackgroundImageWeb then enters its non-string branch and for...of value throws on null instead of omitting the declaration. Add if (value == null) return; before the string check.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: cc6d497d-abef-4abe-ba66-b0d02aec2503

📥 Commits

Reviewing files that changed from the base of the PR and between 08579fb and fe28279.

📒 Files selected for processing (2)

• packages/react-native-reanimated/src/common/web/style/processors/__tests__/backgroundImage.test.ts
• packages/react-native-reanimated/src/common/web/style/processors/backgroundImage.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/react-native-reanimated/src/common/web/style/processors/tests/backgroundImage.test.ts
• packages/react-native-reanimated/src/common/web/style/processors/backgroundImage.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

[MatiPl01]

Closing: the backgroundImage feature stays in #10193, which will be rebased on the prerequisite fixes; the web serializer fixes from here become commits on that branch.