From 6e495b9d59666826e8739d188ecb217dbb977238 Mon Sep 17 00:00:00 2001 From: Dan Stepanov Date: Mon, 14 Sep 2026 15:58:40 -0700 Subject: [PATCH] docs: align v4 and v5 guidance with current releases --- app/docs/layout.tsx | 6 +- app/v5/llms.txt/route.ts | 4 +- components/copy-installation-button.tsx | 279 +--------- components/copy-migration-button.tsx | 524 ++---------------- content/docs/api/use-color-scheme.md | 2 + .../getting-started/installation/_install.mdx | 4 +- .../getting-started/installation/_npm.mdx | 4 +- .../installation/frameworkless.mdx | 10 +- .../getting-started/installation/index.mdx | 18 +- .../docs/getting-started/troubleshooting.mdx | 10 +- content/v5/api/css-interop.mdx | 82 +-- content/v5/api/styled.mdx | 8 +- content/v5/api/use-color-scheme.mdx | 19 +- content/v5/api/vars.mdx | 9 +- content/v5/api/with-nativewind.mdx | 12 + content/v5/core-concepts/dark-mode.mdx | 12 +- content/v5/core-concepts/states.mdx | 10 + .../v5/core-concepts/style-specificity.mdx | 8 +- content/v5/core-concepts/units.mdx | 2 +- content/v5/customization/configuration.mdx | 2 +- .../installation/_additional-guides.mdx | 4 +- .../getting-started/installation/_install.mdx | 20 +- .../v5/getting-started/installation/_npm.mdx | 16 +- .../installation/_tailwind.mdx | 5 +- .../installation/_typescript.mdx | 2 + .../v5/getting-started/installation/index.mdx | 26 +- .../getting-started/installation/nextjs.mdx | 123 +--- .../v5/getting-started/troubleshooting.mdx | 138 +---- content/v5/getting-started/typescript.mdx | 5 +- content/v5/guides/custom-components.mdx | 6 +- content/v5/guides/migrate-from-preview.mdx | 42 ++ content/v5/guides/migrate-from-v4.mdx | 443 ++------------- content/v5/guides/themes.mdx | 21 +- content/v5/guides/third-party-components.mdx | 228 ++------ content/v5/guides/using-with-monorepos.mdx | 14 +- content/v5/index.mdx | 83 +-- content/v5/meta.json | 1 + content/v5/tailwind/_compatibility.mdx | 10 +- content/v5/tailwind/borders/border-color.mdx | 3 +- content/v5/tailwind/borders/border-style.mdx | 7 +- content/v5/tailwind/borders/outline-style.mdx | 3 +- content/v5/tailwind/flexbox/flex-basis.mdx | 3 +- content/v5/tailwind/flexbox/order.mdx | 6 +- .../v5/tailwind/interactivity/caret-color.mdx | 7 +- .../v5/tailwind/interactivity/user-select.mdx | 6 +- content/v5/tailwind/layout/object-fit.mdx | 4 + .../v5/tailwind/layout/object-position.mdx | 4 + content/v5/tailwind/layout/overflow.mdx | 7 +- content/v5/tailwind/layout/position.mdx | 7 +- .../tailwind/layout/top-right-bottom-left.mdx | 3 +- content/v5/tailwind/sizing/height.mdx | 3 +- content/v5/tailwind/sizing/max-height.mdx | 3 +- content/v5/tailwind/sizing/max-width.mdx | 3 +- content/v5/tailwind/sizing/min-height.mdx | 3 +- content/v5/tailwind/sizing/min-width.mdx | 3 +- content/v5/tailwind/sizing/width.mdx | 3 +- .../tailwind/transforms/transform-origin.mdx | 7 +- .../transitions-animation/animation.mdx | 4 + content/v5/tailwind/typography/text-color.mdx | 3 +- .../typography/text-decoration-color.mdx | 3 +- .../typography/text-decoration-style.mdx | 3 +- .../tailwind/typography/text-decoration.mdx | 3 +- .../v5/tailwind/typography/vertical-align.mdx | 3 +- 63 files changed, 521 insertions(+), 1795 deletions(-) create mode 100644 content/v5/guides/migrate-from-preview.mdx diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx index e8d612a..91509f2 100644 --- a/app/docs/layout.tsx +++ b/app/docs/layout.tsx @@ -51,11 +51,11 @@ export default function Layout({ children }: { children: ReactNode }) {

Nativewind v5 -
pre-release
+
RC

- Check out the new features and improvements in the preview - version of Nativewind. + Check out the new features and improvements in the release + candidate of Nativewind.

Nativewind v5 uses Tailwind CSS v4 as a scripting language to create a universal style system for React Native. Built on top of react-native-css, it compiles Tailwind CSS styles into native StyleSheet objects at build time while providing an efficient runtime for conditional styles like hover, focus, media queries, and container queries.', '', diff --git a/components/copy-installation-button.tsx b/components/copy-installation-button.tsx index a3026a3..9bf5d1b 100644 --- a/components/copy-installation-button.tsx +++ b/components/copy-installation-button.tsx @@ -4,284 +4,45 @@ import { useState } from "react"; import { cn } from "@/lib/cn"; // Full markdown content for direct copying -const INSTALLATION_GUIDE_CONTENT = `# Nativewind v5 Installation Guide +const INSTALLATION_GUIDE_CONTENT = `# Nativewind v5 RC0 installation -This guide provides complete installation instructions for Nativewind v5 with Expo. Use this document to initialize projects with your preferred package manager. +Use an Expo 57 app. Tested versions: Expo 57.0.22, React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1. -## Quick Start - -For rapid setup, use the \`rn-new\` CLI tool: - -\`\`\`bash -npx rn-new@next --nativewind -\`\`\` - -This automatically sets up a new Expo project with Nativewind v5, Expo SDK 54, and Tailwind CSS. - -## Manual Installation - -### Step 1: Install Nativewind and Dependencies - -Install \`nativewind\` and its peer dependencies: \`tailwindcss\`, \`react-native-css\`, \`react-native-reanimated\`, and \`react-native-safe-area-context\`. - -#### Package Manager Commands: - -**Expo CLI (Recommended for Expo projects):** -\`\`\`bash -npx expo install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context +\`\`\`sh +npm install --save-exact nativewind@5.0.0-rc.0 react-native-css@3.1.0-rc.0 +npm install --save-dev --save-exact tailwindcss@4.1.12 @tailwindcss/postcss@4.1.12 postcss lightningcss@1.30.1 +npx expo install react-native-reanimated react-native-worklets react-native-safe-area-context expo-system-ui \`\`\` -**npm:** -\`\`\`bash -npm install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context -\`\`\` - -**yarn:** -\`\`\`bash -yarn add nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context -\`\`\` - -**pnpm:** -\`\`\`bash -pnpm install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context -\`\`\` - -**bun:** -\`\`\`bash -bun install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context -\`\`\` - -### Step 2: Install Tailwind CSS and PostCSS - -Install Tailwind CSS and PostCSS as dev dependencies: - -#### Package Manager Commands: - -**Expo CLI (Recommended for Expo projects):** -\`\`\`bash -npx expo install --dev tailwindcss @tailwindcss/postcss postcss -\`\`\` - -**npm:** -\`\`\`bash -npm install --dev tailwindcss @tailwindcss/postcss postcss -\`\`\` +Use the project's existing package manager. Keep both RC packages pinned together. -**yarn:** -\`\`\`bash -yarn add --dev tailwindcss @tailwindcss/postcss postcss +Create postcss.config.mjs (Expo 57 does not discover postcss.config.cjs): +\`\`\`js +export default { plugins: { "@tailwindcss/postcss": {} } }; \`\`\` -**pnpm:** -\`\`\`bash -pnpm install --save-dev tailwindcss @tailwindcss/postcss postcss -\`\`\` - -**bun:** -\`\`\`bash -bun install --dev tailwindcss @tailwindcss/postcss postcss -\`\`\` - -**Optional:** Install \`prettier-plugin-tailwindcss\` to automatically format your Tailwind CSS code. - -### Step 3: Configure PostCSS - -Create a \`postcss.config.mjs\` file in the root of your project (if it doesn't already exist): - -\`\`\`javascript -// postcss.config.mjs -export default { - plugins: { - "@tailwindcss/postcss": {}, - }, -}; -\`\`\` - -### Step 4: Create Global CSS File - -Create a \`global.css\` file in your project root and add the Tailwind directives: - +Create global.css: \`\`\`css -/* global.css */ @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/preflight.css" layer(base); @import "tailwindcss/utilities.css"; - @import "nativewind/theme"; \`\`\` -**Note:** Instead of using the standard \`@tailwind\` directives, Nativewind recommends using the \`@import\` at-rules above for better compatibility with \`react-native-web\`. - -### Step 5: Configure Metro - -Create or modify your \`metro.config.js\` file: - -1. If you don't have a \`metro.config.js\` file, run: - \`\`\`bash - npx expo customize metro.config.js - \`\`\` - -2. Wrap the default config with \`withNativewind\`: - -\`\`\`javascript -// metro.config.js +Wrap the existing Metro configuration, preserving custom settings: +\`\`\`js const { getDefaultConfig } = require("expo/metro-config"); const { withNativewind } = require("nativewind/metro"); - -/** @type {import('expo/metro-config').MetroConfig} */ -const config = getDefaultConfig(__dirname); - -module.exports = withNativewind(config); -\`\`\` - -### Step 6: Import CSS in Your App - -Import the CSS file at the top of your main app file: - -\`\`\`javascript -// App.js -import "./global.css" - -export default function App() { - /* Your App */ -} -\`\`\` - -**Important:** Import your CSS file inside the same file as the top-most component of your app. Do **not** import it in the same file that calls \`AppRegistry.registerComponent\` or your app will not Fast Refresh properly. - -### Step 7: Pin lightningcss Version - -Force \`lightningcss\` to version 1.30.1 in your \`package.json\` to prevent deserialization errors. The configuration differs by package manager: - -#### Package Manager Configurations: - -**npm:** -\`\`\`json -{ - "overrides": { - "lightningcss": "1.30.1" - } -} +module.exports = withNativewind(getDefaultConfig(__dirname)); \`\`\` -**yarn:** -\`\`\`json -{ - "resolutions": { - "lightningcss": "1.30.1" - } -} -\`\`\` - -**pnpm:** -\`\`\`json -{ - "pnpm": { - "overrides": { - "lightningcss": "1.30.1" - } - } -} -\`\`\` - -**bun:** -\`\`\`json -{ - "overrides": { - "lightningcss": "1.30.1" - } -} -\`\`\` - -**Critical:** This step is required to avoid build-time errors related to \`global.css\` deserialization. - -### Step 8: TypeScript Setup (Optional but Recommended) - -If using TypeScript, create a \`nativewind-env.d.ts\` file in your project root: - -\`\`\`typescript -/// - -// NOTE: This file should not be edited and should be committed with your source code. -// It is generated by react-native-css. If you need to move or disable this file, -// please see the documentation. -\`\`\` - -**Quick Alternative:** Run \`npx expo start --clear\` in your Expo project's root directory to generate this file automatically. - -**Important Naming Conventions:** -- Do NOT name this file \`nativewind.d.ts\` -- Do NOT use the same name as a file or folder in the same directory (e.g., \`app.d.ts\` when an \`/app\` folder exists) -- Do NOT use the same name as a folder in \`node_modules\` (e.g., \`react.d.ts\`) - -These naming conflicts will prevent TypeScript from picking up the types correctly. - -## Verify Installation - -Create a test component to verify your setup: - -\`\`\`tsx -// App.tsx -import "./global.css" -import { Text, View } from "react-native"; - -export default function App() { - return ( - - - Welcome to Nativewind! - - - ); -} -\`\`\` - -If you see styled text centered on a white background, Nativewind is working correctly! - -## Key Differences Between Package Managers - -### Installation Commands -- **Expo CLI**: Uses \`npx expo install\` which ensures version compatibility with your Expo SDK -- **npm**: Standard \`npm install\` or \`npm install --dev\` for dev dependencies -- **yarn**: Uses \`yarn add\` or \`yarn add --dev\` for dev dependencies -- **pnpm**: Uses \`pnpm install\` or \`pnpm install --save-dev\` for dev dependencies -- **bun**: Uses \`bun install\` or \`bun install --dev\` for dev dependencies - -### Dependency Resolution (lightningcss pinning) -- **npm, pnpm, bun**: Use \`"overrides"\` field in package.json -- **yarn**: Uses \`"resolutions"\` field in package.json - -### Recommendations -- For Expo projects, prefer using \`npx expo install\` as it handles peer dependency resolution and version compatibility automatically -- After adding the lightningcss override/resolution, reinstall dependencies: - - npm: \`npm install\` - - yarn: \`yarn install\` - - pnpm: \`pnpm install\` - - bun: \`bun install\` - -## Additional Resources - -- [Editor Setup](https://nativewind.dev/v5/getting-started/installation/editor-setup) - Configure your IDE for Nativewind -- [Other Bundlers](https://nativewind.dev/docs/guides/other-bundlers) - Use Nativewind with alternative bundlers -- [Nativewind Documentation](https://nativewind.dev) - Complete documentation and guides - -## Summary Checklist - -- [ ] Install Nativewind and peer dependencies -- [ ] Install Tailwind CSS and PostCSS as dev dependencies -- [ ] Create \`postcss.config.mjs\` with \`@tailwindcss/postcss\` -- [ ] Create \`global.css\` with Tailwind imports -- [ ] Configure \`metro.config.js\` with \`withNativewind\` -- [ ] Import \`global.css\` in your main app component -- [ ] Pin \`lightningcss\` to version 1.30.1 using appropriate package manager field -- [ ] (TypeScript) Create \`nativewind-env.d.ts\` type definitions -- [ ] Test with a simple styled component +Import global.css once from App.tsx or app/_layout.tsx. Keep babel-preset-expo. Remove the v4 Nativewind Babel preset and JSX import source settings if present. Set expo.userInterfaceStyle to automatic in app.json for system theme changes. ---- +Pin lightningcss to 1.30.1 in package manager overrides or resolutions, following the installation guide. Ensure the generated nativewind-env.d.ts belongs to the TypeScript project. Restart Metro and rebuild when native dependencies change. Verify colors, layout, input, themes and navigation on each supported platform; a successful bundle alone does not prove rendering. -**Version:** Nativewind v5 Preview -**Compatible with:** Expo SDK 54+ -**Last Updated:** 2025 +Full installation guide and package manager examples: https://www.nativewind.dev/v5/getting-started/installation +Existing v4 apps: https://www.nativewind.dev/v5/guides/migrate-from-v4 +Previous v5 preview: https://www.nativewind.dev/v5/guides/migrate-from-preview `; interface CopyInstallationButtonProps { @@ -310,7 +71,7 @@ export function CopyInstallationButton({ className = "" }: CopyInstallationButto )} > - {copied ? "Copied!" : "Copy"} + {copied ? "Copied!" : "Copy installation guide"} ); } diff --git a/components/copy-migration-button.tsx b/components/copy-migration-button.tsx index c4dad6a..35ad32a 100644 --- a/components/copy-migration-button.tsx +++ b/components/copy-migration-button.tsx @@ -4,535 +4,109 @@ import { useState } from "react"; import { cn } from "@/lib/cn"; // Full markdown content for direct copying -const MIGRATION_GUIDE_CONTENT = `# Nativewind v4 to v5 Migration Guide +const MIGRATION_GUIDE_CONTENT = `# Migrate Nativewind v4 to v5 RC0 -This guide provides complete instructions for migrating your project from Nativewind v4 (Tailwind CSS v3.4) to Nativewind v5 (Tailwind CSS v4.1). Use this document as a reference for LLM-assisted migration or manual upgrade. +## Choose the migration path -## Table of Contents +This guide targets Nativewind 5.0.0-rc.0 and react-native-css 3.1.0-rc.0 from Nativewind v4, including v4.2.7. V4 remains stable and uses Tailwind CSS 3. If you are already on v5 preview.4, follow [Upgrade a v5 preview](https://www.nativewind.dev/v5/guides/migrate-from-preview). -1. [Prerequisites](#prerequisites) -2. [Quick Migration Steps](#quick-migration-steps) -3. [Breaking Changes](#breaking-changes) -4. [Deprecations](#deprecations) -5. [Configuration Changes](#configuration-changes) -6. [Troubleshooting](#troubleshooting) -7. [New Features](#new-features) +The RC was tested with Expo 57.0.22, React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1. Upgrade and verify an older Expo SDK separately. Do not force native dependency versions just to satisfy a styling migration. ---- +NativewindUI v4 components should remain on Nativewind v4. Use their supported v4 setup instead of partially converting them to v5. -## Prerequisites - -Before upgrading to Nativewind v5, your project **must** meet the following version requirements: - -### Required Dependencies - -- **Tailwind CSS v4.1+**: Nativewind v5 is built on Tailwind v4.1+. Review the [Tailwind CSS v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed steps. - -- **React Native 0.81+**: React Native 0.81 introduces architectural changes that Nativewind v5 relies on, including improvements to the StyleSheet and layout engines. Earlier versions may work with limited functionality, but only 0.81+ is officially supported. - -- **React Native New Architecture**: A number of styles require the new architecture. The old architecture may work with limited functionality, but only the new architecture is officially supported. - -- **React Native Reanimated v4+**: Nativewind v5 uses internal features that depend on Reanimated v4+. Ensure your project uses this version to avoid runtime crashes or build issues. Note: Reanimated v4 introduces its own breaking changes — consult the [Reanimated v4 changelog](https://docs.swmansion.com/react-native-reanimated/). - -- **React Native CSS**: Nativewind previously used a transient dependency on \`react-native-css-interop\`. This library has been renamed to \`react-native-css\`, has been moved to a peer dependency, and will require separate installation. Nativewind will no longer be tied to a specific version of \`react-native-css\` and the two libraries can be updated individually. - ---- - -## Quick Migration Steps - -The simplest way to migrate from Nativewind v4 to v5 is to follow these steps: - -### Step 1: Update Dependencies - -Install the new versions of required packages: +## Use the migration skill \`\`\`bash -# Using Expo CLI (recommended) -npx expo install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context - -# Install Tailwind CSS v4 and PostCSS as dev dependencies -npx expo install --dev tailwindcss @tailwindcss/postcss postcss -\`\`\` - -### Step 2: Update CSS File - -Replace your old CSS directives with the new Tailwind v4 imports in your \`global.css\` (or equivalent): - -\`\`\`css -/* OLD - Remove these */ -@tailwind base; -@tailwind components; -@tailwind utilities; - -/* NEW - Add these */ -@import "tailwindcss/theme.css" layer(theme); -@import "tailwindcss/preflight.css" layer(base); -@import "tailwindcss/utilities.css"; - -@import "nativewind/theme"; -\`\`\` - -### Step 3: Update Babel Config - -Remove Nativewind from your \`babel.config.js\`: - -\`\`\`javascript -// babel.config.js - OLD -module.exports = function (api) { - api.cache(true); - return { - presets: [ - ["babel-preset-expo", { jsxImportSource: "nativewind" }], - "nativewind/babel", - ], - }; -}; - -// babel.config.js - NEW -module.exports = function (api) { - api.cache(true); - return { - presets: ["babel-preset-expo"], - }; -}; +npx skills add nativewind/nativewind --skill nativewind-v4-to-v5 \`\`\` -### Step 4: Create PostCSS Config - -Create a \`postcss.config.mjs\` file in the root of your project: - -\`\`\`javascript -// postcss.config.mjs -export default { - plugins: { - "@tailwindcss/postcss": {}, - }, -}; -\`\`\` - -### Step 5: Update Metro Config - -Update the \`withNativewind\` function call (no longer requires a second argument): +Ask your agent to apply the skill to your app. It includes a read only preflight, checks for custom configuration and component mappings, and recovery instructions. Review the [skill and measured verification scope](https://github.com/nativewind/nativewind/tree/main/skills/nativewind-v4-to-v5). Fixture results do not establish that every application is verified. -\`\`\`javascript -// metro.config.js - OLD -module.exports = withNativeWind(config, { input: './global.css' }); +## 1. Preserve a working baseline -// metro.config.js - NEW -const { withNativewind } = require("nativewind/metro"); -module.exports = withNativewind(config); -\`\`\` +Work on a branch. Preserve your source, package manifests, lockfile and configuration, including any uncommitted work. Record the package manager and exact starting versions. Capture representative screens and interactions before editing, including themes, animations, navigation and third party components. -### Step 6: Override the lightningcss version +## 2. Update the dependency group together -Force \`lightningcss\` to a specific version in your \`package.json\` to avoid deserialization errors with \`global.css\` when building: +Update Nativewind, its engine and Tailwind/PostCSS together in your manifest before installing with your existing package manager: -**npm / bun:** Add to \`package.json\`: \`\`\`json { - "overrides": { + "dependencies": { + "nativewind": "5.0.0-rc.0", + "react-native-css": "3.1.0-rc.0" + }, + "devDependencies": { + "tailwindcss": "4.1.12", + "@tailwindcss/postcss": "4.1.12", "lightningcss": "1.30.1" } } \`\`\` -**yarn:** Add to \`package.json\`: -\`\`\`json -{ - "resolutions": { - "lightningcss": "1.30.1" - } -} -\`\`\` +Merge these entries into your existing manifest; do not replace it. Install PostCSS as shown in the [installation guide](https://www.nativewind.dev/v5/getting-started/installation), and let \`npx expo install\` align Reanimated, Worklets, safe area context and expo-system-ui with your SDK. -**pnpm:** Add to \`package.json\`: -\`\`\`json -{ - "pnpm": { - "overrides": { - "lightningcss": "1.30.1" - } - } -} -\`\`\` - -If you don't pin the \`lightningcss\` version, you may encounter deserialization errors with respect to \`global.css\` when building your app. - -### Step 7: Clear Cache and Restart - -\`\`\`bash -npx expo start --clear -\`\`\` - ---- - -## Breaking Changes - -### Tailwind CSS v4 Changes - -Nativewind v5 adopts all breaking changes from Tailwind CSS v4. Please review the [Tailwind CSS v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) carefully. Key changes include: +Nativewind RC0 requires the exact engine candidate above. The packages cannot be upgraded independently for this release. Remove direct \`react-native-css-interop\` dependencies only after checking that no application or workspace consumer still needs them. -- Renamed utility classes -- Changed default theme values -- Modified spacing scale -- Updated color palette +If npm reports \`ERESOLVE\` from the stale v4/Tailwind 3 graph, do not use \`--force\` or \`--legacy-peer-deps\`. Follow the [tested recovery procedure](https://github.com/nativewind/nativewind/blob/main/skills/nativewind-v4-to-v5/references/installation.md), which saves the intended manifest and lets npm update the styling dependency group without deleting the lockfile. Workspaces require a consumer inventory first. -### Classname Renames +## 3. Convert Tailwind configuration -The following Nativewind classes have been renamed to align with Tailwind v4 standards: +Translate custom theme values, plugins and utilities to Tailwind 4 CSS configuration. Preserve any customizations that do not have a verified replacement. Review the [Tailwind upgrade guide](https://tailwindcss.com/docs/upgrade-guide); utility renames alone do not prove the same native appearance. -- \`elevation-sm\` → \`elevation-xs\` -- \`elevation\` → \`elevation-sm\` - -**Migration:** Search and replace these class names across your codebase. - -### Shadow Utilities (\`shadow-*\`) - -Previously, \`shadow-*\` classes mapped to React Native's legacy shadow props (\`shadowColor\`, \`shadowOffset\`, \`shadowOpacity\`, \`shadowRadius\`). They now map to the \`boxShadow\` style property. - -**Migration Impact:** You may notice visual differences in shadows. Review and adjust shadow classes as needed. - -### Line Height - -Line height numeric values are now parsed as if they had the \`em\` unit. Previously they were parsed as unit-less values. - -**Migration:** Divide old line height values by the font size. For example, if you had \`leading-[24]\` with a \`text-base\` (16px), the new value should be \`leading-[1.5]\` (24/16 = 1.5). - -### \`rem\` Values - -\`rem\` is no longer exported and cannot be changed at runtime. If you require Tailwind CSS to dynamically change values, update your theme to use CSS variables instead of \`rem\`. - -**Migration:** Replace \`rem\` usage with CSS custom properties: - -\`\`\`css -@theme { - --spacing-custom: 1rem; -} -\`\`\` - -### Dynamic Mapping Modifier - -The dynamic mapping modifier has been renamed from \`{}\` to \`@prop\`: - -\`\`\`jsx -/* OLD */ - - -/* NEW */ - -\`\`\` - -**Migration:** Search for \`{}-[\` and replace with \`@prop-[\`. - -### Animation Engine - -Nativewind has switched from using a custom animation engine to Reanimated CSS animations. You may find implementation differences between the two engines. - -**Migration Impact:** Test all animations and adjust as needed. Some timing functions or behaviors may differ. - ---- - -## Deprecations - -Nativewind v5 preserves its core API. Your usage of: - -- \`className\` -- \`styled\` - -...will continue to work without modification. - -However, several features are **deprecated** and will emit runtime warnings during development. These features will be **removed in a future major release**. - -### JSX Transform → Import Rewrites - -Nativewind v5 **removes the JSX transform** that previously injected Tailwind support into individual JSX elements. This has been replaced by a new **import rewrite system**. - -**What Changed:** - -Previously, Nativewind modified your JSX via the \`jsxImportSource\`: - -\`\`\`jsx -// Your code -import { View, Text } from 'react-native'; - - - Hello - -\`\`\` +Replace the Tailwind 3 directives in your root CSS: -Now, the \`import\` statement is rewritten to: - -\`\`\`jsx -import { View, Text } from 'react-native-css/react-native'; -\`\`\` - -**Migration Impact:** This does not require any code changes, but may affect your app if you are performing your own import rewrites. The move to import rewrites is driven by a broader shift in the React Native ecosystem toward publishing compiled libraries. - -### \`cssInterop\` / \`remapProps\` → \`styled()\` - -The \`cssInterop\` and \`remapProps\` APIs are deprecated and replaced with a unified \`styled\` API. - -**Migration:** - -\`\`\`jsx -// OLD - cssInterop -import { cssInterop } from 'nativewind'; -cssInterop(View, { className: 'style' }); - -// NEW - styled (same as cssInterop) -import { styled } from 'nativewind'; -styled(View, { className: 'style' }); - -// OLD - remapProps -import { remapProps } from 'nativewind'; -remapProps(View, { className: 'style' }); - -// NEW - styled with passThrough option -styled(View, { className: 'style' }, { passThrough: true }); -\`\`\` - -By default, \`styled()\` enables the transform globally for that component. Disable this by setting \`global\` to false: - -\`\`\`jsx -const MyComponent = styled(View, { className: 'style' }, { global: false }); -\`\`\` - ---- - -## Configuration Changes - -### JavaScript Theme Functions Removed - -The \`nativewind/theme\` export has been removed. All native functions are now available as CSS functions in your stylesheets. - -#### \`platformColor()\` - -\`\`\`css -/* OLD - JavaScript */ -import { platformColor } from 'nativewind/theme'; - -/* NEW - CSS */ -@theme { - --color-error: platformColor(systemRed, red); -} -\`\`\` - -#### \`hairlineWidth()\` - -\`\`\`css -@theme { - --spacing-hairline: hairlineWidth(); -} -\`\`\` - -#### \`pixelRatio()\` - -\`\`\`css -@theme { - --spacing-doublePixelRatio: calc(pixelRatio(2) * 2); -} -\`\`\` - -#### \`fontScale()\` - -\`\`\`css -@theme { - --spacing-doubleFontScale: calc(fontScale(2) * 2); -} -\`\`\` - -#### \`getPixelSizeForLayoutSize()\` - -\`\`\`css -@theme { - --spacing-custom: getPixelSizeForLayoutSize(42); -} -\`\`\` - -#### \`roundToNearestPixel()\` - -\`\`\`css -@theme { - --spacing-custom: roundToNearestPixel(calc(10 / 3)); -} -\`\`\` - -#### \`platformSelect()\` - -\`\`\`css -/* OLD - JavaScript */ -import { platformSelect } from 'nativewind/theme'; - -/* NEW - CSS with media queries */ -@theme { - --color-error: var(--my-color, green); -} - -@media ios { - :root { - --my-color: red; - } -} - -@media android { - :root { - --my-color: blue; - } -} -\`\`\` - -#### \`pixelRatioSelect()\` / \`fontScaleSelect()\` - -\`\`\`css -/* OLD - JavaScript */ -import { pixelRatioSelect, fontScaleSelect } from 'nativewind/theme'; - -/* NEW - CSS with media queries */ -@theme { - --spacing-custom-pixel: 11; - --spacing-custom-font: 11; -} - -@media (pixelRatio() > 2) { - :root { - --spacing-custom-pixel: 3; - } -} - -@media (fontScale() > 2) { - :root { - --spacing-custom-font: 3; - } -} -\`\`\` - ---- - -## Troubleshooting - -### Common Issues - -#### JSX Transform Errors - -**Symptom:** Build errors related to JSX or imports. - -**Solution:** Ensure you removed Nativewind from your \`babel.config.js\`. Clear Metro cache: - -\`\`\`bash -npx expo start --clear -\`\`\` - -#### Incorrect CSS atRules - -**Symptom:** Styles not applying or build errors. - -**Solution:** Ensure you updated to the new atRules in your CSS file: - -\`\`\`css +\`\`\`css title="global.css" @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/preflight.css" layer(base); @import "tailwindcss/utilities.css"; - @import "nativewind/theme"; \`\`\` -#### Metro Config Issues - -**Symptom:** Build errors or styles not updating. +Keep utilities unlayered so React Native Web defaults do not override them. Add \`@source\` paths for shared workspace components when needed. -**Solution:** Verify \`withNativewind\` is called correctly without a second argument: +Create or update \`postcss.config.mjs\`, preserving unrelated plugins: -\`\`\`javascript -module.exports = withNativewind(config); +\`\`\`js title="postcss.config.mjs" +export default { plugins: { "@tailwindcss/postcss": {} } }; \`\`\` -#### Missing PostCSS Config +Expo 57 does not discover \`postcss.config.cjs\`. Follow the installation guide to pin lightningcss 1.30.1 through your package manager's overrides or resolutions. -**Symptom:** Build fails or Tailwind not compiling. +## 4. Update Babel, Metro and TypeScript -**Solution:** Ensure \`postcss.config.mjs\` exists with correct content: - -\`\`\`javascript -export default { - plugins: { - "@tailwindcss/postcss": {}, - }, -}; -\`\`\` +Remove \`nativewind/babel\` and the Nativewind \`jsxImportSource\` setting from the v4 setup. Keep \`babel-preset-expo\` and unrelated plugins. -#### TypeScript Errors - -**Symptom:** TypeScript complains about \`className\` prop. - -**Solution:** Create \`nativewind-env.d.ts\` in your project root: +\`\`\`js title="metro.config.js" +const { getDefaultConfig } = require("expo/metro-config"); +const { withNativewind } = require("nativewind/metro"); -\`\`\`typescript -/// +module.exports = withNativewind(getDefaultConfig(__dirname)); \`\`\` -Or run \`npx expo start --clear\` to generate it automatically. - ---- - -## New Features - -Nativewind v5 adds support for new React Native styling features introduced in recent versions: - -### CSS Features - -- **\`position: static\`**: Standard CSS positioning ([Tailwind](https://tailwindcss.com/docs/position), [Yoga](https://www.yogalayout.dev/blog/announcing-yoga-3.0#position-static)) - -- **\`align-content: space-evenly\`**: Better multiline container support ([Tailwind](https://tailwindcss.com/docs/place-content#space-evenly), [Yoga](https://www.yogalayout.dev/blog/announcing-yoga-3.0#better-support-for-multiline-containers)) - -- **\`filter()\`**: CSS filters including blur, brightness, contrast, etc. ([Tailwind](https://tailwindcss.com/docs/filter), [React Native](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture#box-shadow-and-filter-style-props)) - -- **\`backgroundImage()\`**: Gradient backgrounds (gradients only) ([Tailwind](https://tailwindcss.com/docs/background-image)) +Wrap your existing Metro config rather than discarding custom resolvers. The v4 \`input\` option is no longer needed. Import the root CSS once in \`App.tsx\` or \`app/_layout.tsx\`. Ensure the generated \`nativewind-env.d.ts\` belongs to your TypeScript project. -- **\`box-sizing\`**: Control how element size is calculated ([Tailwind](https://tailwindcss.com/docs/box-sizing)) +## 5. Review application contracts -- **\`display: contents\`**: Remove element from layout tree while keeping children ([Tailwind](https://tailwindcss.com/docs/display#contents)) +Use [styled](https://www.nativewind.dev/v5/api/styled) for components that need explicit mapping. The RC does not export \`cssInterop\` or \`remapProps\` from Nativewind. Do not mechanically rename those functions: \`styled\` returns a wrapper that must be used, and prop destinations and precedence need to be checked. There is no \`global\` option. \`nativeStyleMapping\` is the current mapping option; \`nativeStyleToProp\` remains a deprecated alias. ---- +For native theme overrides, use \`Appearance.setColorScheme("dark")\` or \`"light"\`. On the Expo 57 target, \`"unspecified"\` restores system appearance. Set \`expo.userInterfaceStyle\` to \`"automatic"\`. Preserve any custom browser theme selection separately. See [Dark Mode](https://www.nativewind.dev/v5/core-concepts/dark-mode). -## Migration Checklist +Prefer [VariableContextProvider](https://www.nativewind.dev/v5/guides/themes) for runtime variables and exclude variables that must remain dynamic from compiler inlining. Cross platform lengths need units, for example \`"80px"\`. \`vars()\`, the Nativewind color scheme hook and \`useUnstableNativeVariable\` remain available; deprecated does not mean removed. -Use this checklist to ensure a complete migration: +Remove legacy \`@cssInterop\` or \`@react-native\` configuration after translating its intent. Qualified native root selectors such as \`:root.dark\` are rejected; use media queries and Appearance on native. -- [ ] Update to React Native 0.81+ with New Architecture enabled -- [ ] Install Nativewind v5 preview and peer dependencies -- [ ] Install Tailwind CSS v4 and PostCSS as dev dependencies -- [ ] Update Reanimated to v4+ -- [ ] Create \`postcss.config.mjs\` with \`@tailwindcss/postcss\` -- [ ] Update \`global.css\` with new Tailwind v4 imports -- [ ] Remove Nativewind from \`babel.config.js\` -- [ ] Update \`metro.config.js\` to remove second argument from \`withNativewind\` -- [ ] Pin \`lightningcss\` to 1.30.1 in \`package.json\` (overrides/resolutions) -- [ ] Clear Metro cache (\`npx expo start --clear\`) -- [ ] Search and replace renamed classes (\`elevation-sm\` → \`elevation-xs\`, etc.) -- [ ] Replace \`{}-[\` with \`@prop-[\` for dynamic modifiers -- [ ] Migrate \`cssInterop\`/\`remapProps\` to \`styled()\` -- [ ] Convert JavaScript theme functions to CSS equivalents -- [ ] Test all animations and shadows -- [ ] Verify TypeScript types are working -- [ ] Test on both iOS and Android -- [ ] Review and apply Tailwind CSS v4 breaking changes +Props such as \`placeholderClassName\`, \`indicatorClassName\`, \`presentationClassName\`, \`cssInterop\` and StatusBar \`className\` no longer have declarations for unsupported v5 mappings. Use native props or explicit supported wrappers. TextInput supports \`className="placeholder:text-gray-500"\`. ---- +Shadows now use React Native \`boxShadow\`, and animations use Reanimated CSS animations. Compare the affected screens with your baseline. See the [RC compatibility guide](https://github.com/nativewind/nativewind/blob/main/docs/rc-compatibility.md) for value and platform limits, including the known Android animation cancellation issue. -## Additional Resources +## 6. Verify and recover -- [Tailwind CSS v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) -- [Reanimated v4 Changelog](https://docs.swmansion.com/react-native-reanimated/) -- [React Native New Architecture](https://reactnative.dev/docs/new-architecture-intro) -- [Nativewind v5 Documentation](https://nativewind.dev) +Restart Metro with \`npx expo start --clear\`. Rebuild native apps when native dependencies or configuration change. Run typechecks and production bundles, then compare actual rendering and interactions on every supported platform. Include theme override and system restoration, mappings, text entry, navigation and animations. ---- +A successful export does not prove visual parity. Report unavailable or failing runtime checks as verification pending. A second migration pass should make no new source or dependency changes. -**Version:** Nativewind v5 Preview -**Migrating From:** Nativewind v4 (Tailwind CSS v3.4) -**Migrating To:** Nativewind v5 (Tailwind CSS v4.1) -**Last Updated:** 2025 -`; +To revert, restore only this migration's changes from your source, manifest, lockfile and configuration snapshots. Reinstall with the same package manager and rebuild if native dependencies changed. Preserve unrelated user work.`; interface CopyMigrationButtonProps { className?: string; diff --git a/content/docs/api/use-color-scheme.md b/content/docs/api/use-color-scheme.md index 1eb1199..ed62b1d 100644 --- a/content/docs/api/use-color-scheme.md +++ b/content/docs/api/use-color-scheme.md @@ -30,3 +30,5 @@ function MyComponent() { ); } ``` + +Nativewind v4.2.7 handles the React Native Appearance `unspecified` value internally. Continue using `setColorScheme("system")` with the v4 Nativewind hook to restore system preference; the v5 direct Appearance recipe is a separate API. diff --git a/content/docs/getting-started/installation/_install.mdx b/content/docs/getting-started/installation/_install.mdx index 4c1d5d2..fcbd926 100644 --- a/content/docs/getting-started/installation/_install.mdx +++ b/content/docs/getting-started/installation/_install.mdx @@ -9,7 +9,7 @@ You will need to install `nativewind` and its peer dependencies `tailwindcss`, ` \ No newline at end of file +/> diff --git a/content/docs/getting-started/installation/_npm.mdx b/content/docs/getting-started/installation/_npm.mdx index 3cfebfb..5f76cb1 100644 --- a/content/docs/getting-started/installation/_npm.mdx +++ b/content/docs/getting-started/installation/_npm.mdx @@ -12,7 +12,7 @@ import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; {[ props.deps?.length ? `npm install ${props.deps.join(" ")}` : undefined, props.devDeps?.length - ? `npm install --dev ${props.devDeps.join(" ")}` + ? `npm install --save-dev ${props.devDeps.join(" ")}` : undefined, ] .filter(Boolean) @@ -78,4 +78,4 @@ import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; )} - \ No newline at end of file + diff --git a/content/docs/getting-started/installation/frameworkless.mdx b/content/docs/getting-started/installation/frameworkless.mdx index c17b4da..1bed398 100644 --- a/content/docs/getting-started/installation/frameworkless.mdx +++ b/content/docs/getting-started/installation/frameworkless.mdx @@ -7,12 +7,12 @@ import Install from './_install.mdx'; {/* # Installation */} > Nativewind works with both Expo and framework-less React Native projects but Expo provides a more streamlined experience. -> +> > **Web**: If you'd like to use Metro to bundle for a website or App Clip and you are **not** using Expo, you will need either Expo's Metro config `@expo/metro-config` or to manually use Tailwind CLI to generate a CSS file. -Expo -| Framework-less +Expo +| Framework-less | Next.js Before installing Nativewind, you will need to [initialize your project with the React Native Community CLI](https://reactnative.dev/docs/getting-started-without-a-framework). @@ -23,6 +23,8 @@ Before installing Nativewind, you will need to [initialize your project with the +Nativewind v4.2.7 supports Reanimated 3 and 4. Choose a version compatible with your React Native release. Reanimated 4 also requires a compatible `react-native-worklets`; do not add Worklets to a Reanimated 3 setup. Keep the Nativewind Babel preset below. + Run `pod-install` to finish installation of `react-native-reanimated` ```bash @@ -63,4 +65,4 @@ module.exports = withNativeWind(config, { input: "./global.css" }); ./_try-it-out.mdx -./_additional-guides.mdx \ No newline at end of file +./_additional-guides.mdx diff --git a/content/docs/getting-started/installation/index.mdx b/content/docs/getting-started/installation/index.mdx index 0f2c4b1..0831df2 100644 --- a/content/docs/getting-started/installation/index.mdx +++ b/content/docs/getting-started/installation/index.mdx @@ -8,11 +8,11 @@ import RnNewCommand from './_rn-new-command.mdx'; {/* # Installation */} > Nativewind works with both Expo and framework-less React Native projects but Expo provides a more streamlined experience. -> +> > **Web**: If you'd like to use Metro to bundle for a website or App Clip and you are **not** using Expo, you will need either Expo's Metro config `@expo/metro-config` or to manually use Tailwind CLI to generate a CSS file. -Expo -| Framework-less +Expo +| Framework-less | Next.js @@ -21,6 +21,16 @@ import RnNewCommand from './_rn-new-command.mdx'; +## Nativewind v4.2.7 + +Nativewind v4.2.7 adds Expo SDK 57 support and includes react-native-css-interop 0.2.7. It keeps the Tailwind CSS 3 configuration, Nativewind Babel preset and `withNativeWind(config, { input })` integration. Upgrading within v4 does not require a v5 migration. + +For an existing v4 app, update with your package manager, for example `npm install nativewind@4.2.7`. Keep the native package versions compatible with your Expo SDK. On Expo 57, install `react-native-worklets` alongside Reanimated 4 with `npx expo install react-native-reanimated react-native-worklets react-native-safe-area-context`. Older projects using Reanimated 3 should retain their compatible setup instead of adding Worklets just for this patch. + +Restart Metro after upgrading. Rebuild the native app if you change native dependencies. Check animations and system appearance on each supported platform. + +Looking for the v5 release candidate? Use the separate [v5 installation guide](/v5/getting-started/installation) or [migration guide](/v5/guides/migrate-from-v4). + ## Installation with Expo ### 1. Install Nativewind @@ -78,4 +88,4 @@ Switch the bundler to use the [Metro bundler](https://docs.expo.dev/guides/custo ./_try-it-out.mdx -./_additional-guides.mdx \ No newline at end of file +./_additional-guides.mdx diff --git a/content/docs/getting-started/troubleshooting.mdx b/content/docs/getting-started/troubleshooting.mdx index 7edbaed..f56718a 100644 --- a/content/docs/getting-started/troubleshooting.mdx +++ b/content/docs/getting-started/troubleshooting.mdx @@ -10,9 +10,9 @@ While troubleshooting, always start your application without the cache! - Framework-less React Native: `npx react-native start --reset-cache` -Before troubleshooting Nativewind, it's crucial to ensure that Tailwind CSS itself is functioning correctly. Nativewind uses the Tailwind CLI to compile your styles, so any issues with the Tailwind CLI should be resolved first. +Before troubleshooting Nativewind, it's crucial to ensure that Tailwind CSS itself is functioning correctly. Nativewind uses the Tailwind CLI to compile your styles, so any issues with the Tailwind CLI should be resolved first. -Using the command `npx tailwindcss --input --output output.css`, the Tailwind CLI will generate an `output.css` file. **The `` should be your project's main CSS file (typically `global.css` or `styles.css`) that contains the `@import 'tailwindcss';` directive.** +Using the command `npx tailwindcss --input --output output.css`, the Tailwind CLI will generate an `output.css` file. **The `` should be your project's main CSS file (typically `global.css` or `styles.css`) that contains the Tailwind 3 directives `@tailwind base;`, `@tailwind components;` and `@tailwind utilities;`.** For example: ```bash @@ -83,12 +83,12 @@ By itself, this information may or may not be useful to you, but it is extremely ```cmd set "DEBUG=nativewind" && script output.log ``` - + **Note:** For older Windows versions, use: ```cmd set "DEBUG=nativewind" && > output.log 2>output.log ``` - + **For PowerShell:** ```powershell $env:DEBUG="nativewind"; *> output.log @@ -138,4 +138,4 @@ React Native uses a different base flex definition than the web. This can be fix ### Flex Direction -React Native uses a different default `flex-direction` than the web. This can be fixed by explicitly setting a `flex-direction`. \ No newline at end of file +React Native uses a different default `flex-direction` than the web. This can be fixed by explicitly setting a `flex-direction`. diff --git a/content/v5/api/css-interop.mdx b/content/v5/api/css-interop.mdx index d08f7a5..f368dc2 100644 --- a/content/v5/api/css-interop.mdx +++ b/content/v5/api/css-interop.mdx @@ -1,84 +1,22 @@ --- -title: cssInterop & remapProps +title: Migrating cssInterop and remapProps --- -{/* # cssInterop & remapProps */} +Nativewind v5 RC0 does not export `cssInterop` or `remapProps`. Those APIs belong to the [v4 documentation](/docs/api/css-interop). -These functions enable `className` support on components that don't natively handle it. They are primarily used for third-party components. - - -For your own components, you don't need these functions. Simply accept and pass through `className`. See [Writing Custom Components](../guides/custom-components). - - -## cssInterop - -`cssInterop` tags a component so the Nativewind runtime resolves `className` strings into styles. Use it when a third-party component accepts a `style` prop but doesn't pass through `className`. - -```tsx -import { cssInterop } from "nativewind"; -import { MapView } from "react-native-maps"; - -cssInterop(MapView, { className: "style" }); - -// Now you can use className - -``` - -### Mapping to specific props - -Some components use props other than `style` for styling: - -```tsx -cssInterop(component, { - className: { - target: "style", - nativeStyleToProp: { - height: true, - width: true, - }, - }, -}); -``` - -With `nativeStyleToProp`, style properties are extracted from the resolved styles and passed as individual props. This is useful for components like SVGs that expect `height`/`width` as props on native. - -### Multiple className props - -Components with multiple style props can accept multiple className props: - -```tsx -cssInterop(FlatList, { - className: "style", - contentContainerClassName: "contentContainerStyle", -}); - - -``` - -## remapProps - -`remapProps` is a simpler alternative to `cssInterop` for components that just need prop renaming: +Use [styled](/v5/api/styled) to create a wrapper for a component that needs className mapping, and render the returned wrapper: ```tsx -import { remapProps } from "nativewind"; +import { styled } from "nativewind"; +import { ThirdPartyView } from "third-party-library"; -const CustomButton = remapProps(ThirdPartyButton, { - buttonClass: "buttonStyle", - labelClass: "labelStyle", -}); +const StyledView = styled(ThirdPartyView, { className: "style" }); - +; ``` -Options: +`styled` does not globally register or mutate the original component. There is no `global` option. Do not mechanically rename a v4 call and keep rendering the original component. -```tsx -// Map a new prop to an existing style prop -remapProps(component, { newProp: "existingStyleProp" }); +For wrappers that forward styles to another styled component, `styled` accepts `{ passThrough: true }` as its third argument. This requires a compatible downstream consumer; it does not produce ordinary resolved styles for arbitrary third party code. -// Override an existing prop to accept className -remapProps(component, { existingProp: true }); -``` +Review each prop destination, nested mapping and explicit prop precedence. Use `nativeStyleMapping` to extract styles into props; `nativeStyleToProp` is still a deprecated alias. See [third party components](/v5/guides/third-party-components) and the [v4 migration guide](/v5/guides/migrate-from-v4). diff --git a/content/v5/api/styled.mdx b/content/v5/api/styled.mdx index e9909e4..6ec1ee9 100644 --- a/content/v5/api/styled.mdx +++ b/content/v5/api/styled.mdx @@ -17,6 +17,8 @@ const StyledComponent = styled(SomeNativeComponent); ``` +Define the wrapper outside render and use the returned component. The original component is unchanged; `styled` does not register it globally and has no `global` option. + ## Mapping Styles to Props Some React Native components expect style values as direct props rather than inside a `style` object. Use `styled` to extract specific style properties and pass them as props: @@ -28,7 +30,7 @@ import { Svg, Circle } from "react-native-svg"; const StyledSvg = styled(Svg, { className: { target: "style", - nativeStyleToProp: { + nativeStyleMapping: { height: true, width: true, }, @@ -37,8 +39,8 @@ const StyledSvg = styled(Svg, { const StyledCircle = styled(Circle, { className: { - target: "style", - nativeStyleToProp: { + target: false, + nativeStyleMapping: { fill: true, stroke: true, strokeWidth: true, diff --git a/content/v5/api/use-color-scheme.mdx b/content/v5/api/use-color-scheme.mdx index a7666b3..e2e925a 100644 --- a/content/v5/api/use-color-scheme.mdx +++ b/content/v5/api/use-color-scheme.mdx @@ -20,14 +20,12 @@ Replace the Nativewind import with the React Native equivalent: The v4 API returned `{ colorScheme, setColorScheme, toggleColorScheme }`. In v5, use the React Native APIs directly: ```tsx -import { useColorScheme, Appearance } from "react-native"; +import { useColorScheme, Appearance, Pressable, Text } from "react-native"; function ThemeToggle() { const colorScheme = useColorScheme(); - const setColorScheme = (scheme) => { - Appearance.setColorScheme(scheme); - }; + const restoreSystemTheme = () => Appearance.setColorScheme("unspecified"); const toggleColorScheme = () => { Appearance.setColorScheme( @@ -36,11 +34,18 @@ function ThemeToggle() { }; return ( - - Current: {colorScheme} - + <> + + Current: {colorScheme} + + + Use system theme + + ); } ``` +The `"unspecified"` value restores system appearance on the Expo 57 native target. Browser manual theme controls need separate handling. + See the [Dark Mode](../core-concepts/dark-mode) guide for more details. diff --git a/content/v5/api/vars.mdx b/content/v5/api/vars.mdx index 3ec7b6b..d2f0442 100644 --- a/content/v5/api/vars.mdx +++ b/content/v5/api/vars.mdx @@ -4,6 +4,8 @@ title: vars() & useUnstableNativeVariable() {/* # vars() & useUnstableNativeVariable() */} +`vars()` is deprecated but remains available in RC0. Prefer `VariableContextProvider` for new code. Preserve runtime variables with `inlineVariables.exclude` when the compiler would otherwise inline them; see [Dynamic Themes](/v5/guides/themes). + ## vars() `vars` is a function that takes a dictionary of CSS variables and returns a style object. When applied to a component's `style` prop, the variables flow down the component tree, just like CSS custom properties. @@ -15,7 +17,7 @@ import { vars } from "nativewind"; function ThemedSection({ brandColor }) { return ( - Themed text + Themed text ); } @@ -36,12 +38,13 @@ Variables set with `vars()` can be consumed by any descendant component using `v `VariableContextProvider` sets CSS variables via React context rather than the `style` prop. This is useful when you need variables available to components that aren't direct style descendants: ```tsx +import { Text } from "react-native"; import { VariableContextProvider } from "nativewind"; function App() { return ( - - Blue text + + Blue text ); } diff --git a/content/v5/api/with-nativewind.mdx b/content/v5/api/with-nativewind.mdx index e6c98d3..910c3ee 100644 --- a/content/v5/api/with-nativewind.mdx +++ b/content/v5/api/with-nativewind.mdx @@ -15,6 +15,18 @@ const config = getDefaultConfig(__dirname); module.exports = withNativewind(config); ``` +## Runtime variables + +To keep a CSS variable dynamic instead of compiling its default value into native styles: + +```js +module.exports = withNativewind(config, { + inlineVariables: { exclude: ["--color-primary"] }, +}); +``` + +See [Dynamic Themes](/v5/guides/themes) for provider examples. + ## Options `withNativewind` accepts an optional second argument with the same options as `withReactNativeCSS` from `react-native-css/metro`. The following defaults are applied: diff --git a/content/v5/core-concepts/dark-mode.mdx b/content/v5/core-concepts/dark-mode.mdx index ab54149..f28c3af 100644 --- a/content/v5/core-concepts/dark-mode.mdx +++ b/content/v5/core-concepts/dark-mode.mdx @@ -8,7 +8,7 @@ Nativewind v5 supports dark mode through the system preference using the `prefer ## System Preference (Automatic) -By default, Tailwind CSS's `dark:` variant uses the system color scheme. No additional configuration is needed: +By default, Tailwind CSS's `dark:` variant uses the system color scheme. In Expo, install `expo-system-ui` and set `"userInterfaceStyle": "automatic"` in the `expo` object of `app.json`. Rebuild when native configuration changes: ```tsx import { View, Text } from "react-native"; @@ -31,7 +31,7 @@ Under the hood, `dark:` maps to `@media (prefers-color-scheme: dark)`, which is To allow users to manually toggle between light and dark mode, use React Native's `Appearance` API: ```tsx -import { Appearance } from "react-native"; +import { Appearance, Pressable, Text } from "react-native"; function ThemeToggle() { const toggleTheme = () => { @@ -48,6 +48,14 @@ function ThemeToggle() { } ``` +On the Expo 57 target, restore the system preference with: + +```tsx +Appearance.setColorScheme("unspecified"); +``` + +This manual override is for native. React Native Web does not turn it into a browser theme selector. Keep browser theme selection separate if your app supports a manual browser toggle. Qualified selectors such as `:root.dark` are rejected by the native compiler; use media queries on native. + You can read the current color scheme using React Native's `useColorScheme` hook: ```tsx diff --git a/content/v5/core-concepts/states.mdx b/content/v5/core-concepts/states.mdx index e6d32e8..18d9208 100644 --- a/content/v5/core-concepts/states.mdx +++ b/content/v5/core-concepts/states.mdx @@ -134,3 +134,13 @@ Use `ltr:` and `rtl:` to apply styles based on the text direction: Direction-aware text ``` + +## ARIA state modifiers in RC0 + +Use the public React Native prop, for example: + +```tsx + +``` + +`accessibilityState={{ selected }}` does not activate `aria-selected:` in this RC, and `ariaSelected` is not the public React Native prop. The engine matches the incoming `aria-selected` prop before React Native translates it for the native host. diff --git a/content/v5/core-concepts/style-specificity.mdx b/content/v5/core-concepts/style-specificity.mdx index f13975a..54f7b1d 100644 --- a/content/v5/core-concepts/style-specificity.mdx +++ b/content/v5/core-concepts/style-specificity.mdx @@ -31,11 +31,11 @@ Styles are applied in the following order of precedence (lowest to highest): ## Important -The `!` prefix (Tailwind's `!important` syntax) overrides both normal class styles and inline styles: +The `!` suffix (Tailwind's `!important` syntax) overrides both normal class styles and inline styles: ```tsx -// !text-white overrides the inline style - +// text-white! overrides the inline style + // Result: color is "#fff" ``` @@ -46,7 +46,7 @@ Nativewind automatically merges `className` styles with the `style` prop. When t ```tsx // className sets padding, style sets color — both are applied -// Result: { padding: 16, backgroundColor: "red" } +// Result: { padding: 14, backgroundColor: "red" } ``` When they target the same property, `style` takes precedence: diff --git a/content/v5/core-concepts/units.mdx b/content/v5/core-concepts/units.mdx index debc327..142a975 100644 --- a/content/v5/core-concepts/units.mdx +++ b/content/v5/core-concepts/units.mdx @@ -68,4 +68,4 @@ You can override the `rem` value using CSS: } ``` -Or inline using a CSS variable on a parent component. +The `rem` value is not a runtime JavaScript setting in v5. For dimensions that change at runtime, use a CSS variable through `VariableContextProvider` and preserve it with `inlineVariables.exclude`; see [Dynamic Themes](/v5/guides/themes). diff --git a/content/v5/customization/configuration.mdx b/content/v5/customization/configuration.mdx index 065daa7..46cd701 100644 --- a/content/v5/customization/configuration.mdx +++ b/content/v5/customization/configuration.mdx @@ -44,7 +44,7 @@ See the [withNativewind API reference](../api/with-nativewind) for available opt ## Babel Configuration -Nativewind v5 does not require any Babel configuration. The babel plugin is applied automatically by the Metro config. If you had `nativewind/babel` in your `babel.config.js` from v4, remove it. +The Nativewind import rewrite plugin is applied by the Metro integration. Keep `babel-preset-expo` and unrelated Babel plugins. Remove the v4 `nativewind/babel` preset and Nativewind `jsxImportSource` setting. ## Optional: tailwind.config.js diff --git a/content/v5/getting-started/installation/_additional-guides.mdx b/content/v5/getting-started/installation/_additional-guides.mdx index 135b33b..d72f500 100644 --- a/content/v5/getting-started/installation/_additional-guides.mdx +++ b/content/v5/getting-started/installation/_additional-guides.mdx @@ -4,5 +4,5 @@ title: Additional Setup Guides ## Additional Setup Guides -- [Editor Setup](./editor-setup) - Learn how to set up your editor to use Nativewind -- [Other Bundlers](/docs/guides/other-bundlers) - Learn how to use Nativewind with other bundlers \ No newline at end of file +- [Editor Setup](/v5/getting-started/editor-setup) - Learn how to set up your editor to use Nativewind +- [Other Bundlers](/v5/guides/other-bundlers) - Learn how to use Nativewind with other bundlers diff --git a/content/v5/getting-started/installation/_install.mdx b/content/v5/getting-started/installation/_install.mdx index 8f7fca3..5083c7f 100644 --- a/content/v5/getting-started/installation/_install.mdx +++ b/content/v5/getting-started/installation/_install.mdx @@ -4,14 +4,14 @@ title: _install helper import NPM from "./_npm.mdx"; -You will need to install `nativewind` and its peer dependencies `tailwindcss`, `react-native-css`, `react-native-reanimated`, and `react-native-safe-area-context`. +Install the exact RC pair together. Nativewind 5.0.0-rc.0 requires react-native-css 3.1.0-rc.0; do not combine the RC with an unpinned engine. - + + +In an Expo project, let Expo select compatible native dependencies: + +```bash +npx expo install react-native-reanimated react-native-worklets react-native-safe-area-context expo-system-ui +``` + +The tested target is Expo 57.0.22, React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1. The engine declares React Native >=0.81 and @expo/metro-config >=54 minimums; those minimums do not establish RC verification on every older SDK. Handle an Expo SDK upgrade separately from the styling migration. diff --git a/content/v5/getting-started/installation/_npm.mdx b/content/v5/getting-started/installation/_npm.mdx index 3df0c3a..4a47339 100644 --- a/content/v5/getting-started/installation/_npm.mdx +++ b/content/v5/getting-started/installation/_npm.mdx @@ -38,10 +38,10 @@ import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock"; 
         {[
           props.deps?.length
-            ? `npm install ${props.deps.join(" ")}`
+            ? `npm install ${props.exact ? "--save-exact " : ""}${props.deps.join(" ")}`
             : undefined,
           props.devDeps?.length
-            ? `npm install --dev ${props.devDeps.join(" ")}`
+            ? `npm install --save-dev ${props.exact ? "--save-exact " : ""}${props.devDeps.join(" ")}`
             : undefined,
         ]
           .filter(Boolean)
@@ -53,9 +53,9 @@ import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
     
       
         {[
-          props.deps?.length ? `yarn add ${props.deps.join(" ")}` : undefined,
+          props.deps?.length ? `yarn add ${props.exact ? "--exact " : ""}${props.deps.join(" ")}` : undefined,
           props.devDeps?.length
-            ? `yarn add --dev ${props.devDeps.join(" ")}`
+            ? `yarn add --dev ${props.exact ? "--exact " : ""}${props.devDeps.join(" ")}`
             : undefined,
         ]
           .filter(Boolean)
@@ -68,10 +68,10 @@ import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
       
         {[
           props.deps?.length
-            ? `pnpm install ${props.deps.join(" ")}`
+            ? `pnpm add ${props.exact ? "--save-exact " : ""}${props.deps.join(" ")}`
             : undefined,
           props.devDeps?.length
-            ? `pnpm install --save-dev ${props.devDeps.join(" ")}`
+            ? `pnpm add --save-dev ${props.exact ? "--save-exact " : ""}${props.devDeps.join(" ")}`
             : undefined,
         ]
           .filter(Boolean)
@@ -84,10 +84,10 @@ import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
       
         {[
           props.deps?.length
-            ? `bun install ${props.deps.join(" ")}`
+            ? `bun add ${props.exact ? "--exact " : ""}${props.deps.join(" ")}`
             : undefined,
           props.devDeps?.length
-            ? `bun install --dev ${props.devDeps.join(" ")}`
+            ? `bun add --dev ${props.exact ? "--exact " : ""}${props.devDeps.join(" ")}`
             : undefined,
         ]
           .filter(Boolean)
diff --git a/content/v5/getting-started/installation/_tailwind.mdx b/content/v5/getting-started/installation/_tailwind.mdx
index af7c17e..e3927c2 100644
--- a/content/v5/getting-started/installation/_tailwind.mdx
+++ b/content/v5/getting-started/installation/_tailwind.mdx
@@ -8,8 +8,9 @@ import { Callout } from "@/components/callout";
 **Install Tailwind CSS**
 
 
 
 Optionally, install `prettier-plugin-tailwindcss` as a dev dependency to automatically format your Tailwind CSS code.
diff --git a/content/v5/getting-started/installation/_typescript.mdx b/content/v5/getting-started/installation/_typescript.mdx
index b8bff0a..f017197 100644
--- a/content/v5/getting-started/installation/_typescript.mdx
+++ b/content/v5/getting-started/installation/_typescript.mdx
@@ -24,3 +24,5 @@ Do not call this file:
 By doing so, your types will not be picked up by the TypeScript compiler.
 
 
+
+Ensure this declaration file is included by your tsconfig. If TypeScript reports an unresolved side effect CSS import, add `declare module "*.css";` to an application declaration file included by that project. Do not retain obsolete v4 declarations to silence missing RC props.
diff --git a/content/v5/getting-started/installation/index.mdx b/content/v5/getting-started/installation/index.mdx
index 3490a8a..4dda572 100644
--- a/content/v5/getting-started/installation/index.mdx
+++ b/content/v5/getting-started/installation/index.mdx
@@ -7,6 +7,9 @@ import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import Install from "./_install.mdx";
 import TailwindInstall from "./_tailwind.mdx";
 import { Callout } from "@/components/callout";
+import { CopyInstallationButton } from "@/components/copy-installation-button";
+
+
 
 {/* # Installation */}
 
@@ -30,7 +33,7 @@ import { Callout } from "@/components/callout";
  */}
 
 
- If you'd like to skip manual setup and use Nativewind, you can use the following command to initialize a new Expo project with Nativewind v5, Expo SDK 54, and Tailwind CSS.
+ If you'd like to skip manual setup and use Nativewind, you can use the following command to initialize a new Expo project with Nativewind v5 and Tailwind CSS. Check the generated package versions against the RC target below.
 
 
   
@@ -57,6 +60,10 @@ bunx rn-new@next --nativewind
 
 
 
+## Nativewind v5 RC0
+
+These instructions target `nativewind@5.0.0-rc.0` with `react-native-css@3.1.0-rc.0`. V4 remains the stable release. Existing apps should follow [Migrate from v4](/v5/guides/migrate-from-v4) or [Upgrade a v5 preview](/v5/guides/migrate-from-preview).
+
 ## Installation with Expo
 
 ### 1. Install Nativewind
@@ -71,7 +78,7 @@ bunx rn-new@next --nativewind
 
 Create a `postcss.config.mjs` file in the root of your Expo project if you don't already have one, then add `@tailwindcss/postcss` there, or wherever PostCSS is configured in your project.
 
-```jsx title="postcss.config.mjs
+```js title="postcss.config.mjs"
 export default {
   plugins: {
     "@tailwindcss/postcss": {},
@@ -79,6 +86,8 @@ export default {
 };
 ```
 
+Expo 57 discovers `postcss.config.js` and `postcss.config.mjs`; do not name this file `postcss.config.cjs`.
+
 Create a `global.css` file and add the Tailwind directives.
 
 ```css title="global.css"
@@ -92,8 +101,7 @@ Create a `global.css` file and add the Tailwind directives.
 > From here onwards, replace `./global.css` with the relative path to the CSS file you just created.
 
 
-  Instead of using the standard `@tailwind`, Nativewind recommends using the
-  at-rules above which provide better compatibility with `react-native-web`
+  Keep utilities unlayered as shown above. A single `@import "tailwindcss"` can put utilities below React Native Web defaults in the CSS cascade, even when the build succeeds.
 
 
 ### 3. Create or modify your metro.config.js
@@ -113,10 +121,10 @@ module.exports = withNativewind(config);
 ### 4. Import your CSS file
 
 ```js title="App.js"
-import "./global.css"
+import "./global.css";
 
-export default App() {
-  /* Your App */
+export default function App() {
+  return null; // Replace with your app.
 }
 ```
 
@@ -126,6 +134,10 @@ export default App() {
   `AppRegistry.registerComponent` or your app will not Fast Refresh properly.
 
 
+For Expo Router, import the CSS once in `app/_layout.tsx`. Keep `babel-preset-expo` and any unrelated Babel plugins; remove only the v4 Nativewind preset and JSX import source settings.
+
+For system appearance, install `expo-system-ui` as above and set `"userInterfaceStyle": "automatic"` inside the `expo` object in `app.json`. Rebuild after changing native dependencies or native configuration.
+
 ### 5. Override the lightningcss version
 
 Force `lightningcss` to a specific version in your `package.json`:
diff --git a/content/v5/getting-started/installation/nextjs.mdx b/content/v5/getting-started/installation/nextjs.mdx
index 784d762..321bbfd 100644
--- a/content/v5/getting-started/installation/nextjs.mdx
+++ b/content/v5/getting-started/installation/nextjs.mdx
@@ -1,124 +1,11 @@
 ---
-title: Installation
+title: Next.js
 ---
 
-{/* # Installation */}
+The v5 RC is verified with the Expo 57 Metro integration. A complete Next.js integration has not been verified for this candidate.
 
-> Nativewind works with both Expo and framework-less React Native projects but Expo provides a more streamlined experience.
-> 
-> **Web**: If you'd like to use Metro to bundle for a website or App Clip and you are **not** using Expo, you will need either Expo's Metro config `@expo/metro-config` or to manually use Tailwind CLI to generate a CSS file.
+The v4 recipe using `nativewind/preset`, `jsxImportSource: "nativewind"` and `react-native-css-interop` does not apply to v5. Do not copy that setup into an RC project.
 
+For a supported starting point, use the [Expo installation](/v5/getting-started/installation), including its web target. Projects maintaining a v4 Next.js integration should use the [v4 Next.js guide](/docs/getting-started/installation/nextjs).
 
-Expo 
-| Framework-less 
-| Next.js
-
-## Installation with Next.js
-
-Nativewind can be used in a Next.js project that is already configured to use Expo or framework-less React Native Web.
-
-Setting up a new Next.js project to use React Native Web is out of scope for these instructions.
-
-> Nativewind will only work with the `/pages` router or on `"use client"` routes. RSC support is in progress.
-
-### 1. Setup Tailwind CSS
-
-Simply configure Next.js as per [the Tailwind CSS Next.js setup guide](https://v3.tailwindcss.com/docs/guides/nextjs)
-
-### 2. Add the Nativewind preset
-
-```diff title="tailwind.config.js"
-
-module.exports = {
-  content: [
-    './pages/**/*.{js,jsx,ts,tsx}',
-  ],
-+ presets: [require('nativewind/preset')],
-  theme: {
-    extend: {},
-  },
-}
-```
-
-### 3. Update import source
-
-Nativewind requires the `jsxImportSource` to be set to `nativewind`. The option to configure this depends on how you are compiling your Next.js project.
-
-
-  
-    
-    Next.js uses a `jsconfig.json`/`tsconfig.json` file to configure the `jsxImportSource`.
-
-    ```json title="tsconfig.json"
-    {
-      "compilerOptions": {
-        "jsxImportSource": "nativewind"
-      }
-    }
-    ```
-  
-  
-    ```diff title="babel.config.js"
-    module.exports = {
-      presets: ["next/babel"],
-    +  plugins: [
-    +    [
-    +      "@babel/plugin-transform-react-jsx",
-    +      {
-    +        runtime: "automatic",
-    +        importSource: "nativewind",
-    +      },
-    +    ],
-    +  ],
-    };
-
-    ```
-  
-
-
-### 4. Transpile Nativewind
-
-```diff title="next.config.js"
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-+  transpilePackages: ["nativewind", "react-native-css-interop"],
-}
-```
-
-## Common issues
-
-### Errors about package imports.
-
-```
-import typeof AccessibilityInfo from './Libraries/Components/AccessibilityInfo/AccessibilityInfo';
-^^^^^^
-
-SyntaxError: Cannot use import statement outside a module
-```
-
-This signals that you have incorrectly setup React Native Web and/or a dependency needs to be added to `transpilePackages`. This is out of scope for Nativewind.
-
-### Styles are not being applied
-
-A common issue with Next.js is your styles are imported, but are being overridden by another StyleSheet due to the stylesheet import order.
-
-A simple fix is simply make the Tailwind styles a higher specificity.
-
-```diff title=tailwind.config.json
-module.exports = {
-  content: [
-    './pages/**/*.{js,jsx,ts,tsx}',
-  ],
-  plugins: [require('nativewind/tailwind/css')],
-+ important: 'html',
-  theme: {
-    extend: {},
-  },
-}
-```
-
-## Additional Setup Guides
-
-- [Using with Monorepos](./using-with-monorepos) - Learn how to set up Nativewind in monorepo environments like NX
-- [Other Bundlers](/docs/guides/other-bundlers) - Learn how to use Nativewind with other bundlers
\ No newline at end of file
+A v5 integration outside Metro needs Tailwind 4/PostCSS compilation, React Native Web setup and the appropriate component import transforms. Installing the package pair alone does not provide those pieces. Verify rendering, navigation and production output before treating a custom integration as supported.
diff --git a/content/v5/getting-started/troubleshooting.mdx b/content/v5/getting-started/troubleshooting.mdx
index f781d4e..1b98b37 100644
--- a/content/v5/getting-started/troubleshooting.mdx
+++ b/content/v5/getting-started/troubleshooting.mdx
@@ -1,141 +1,53 @@
 ---
 title: Troubleshooting
 ---
-{/* # Troubleshooting */}
 
-
-While troubleshooting, always start your application without the cache!
+## Check versions and restart
 
-- Expo: `npx expo start --clear`
-- Framework-less React Native: `npx react-native start --reset-cache`
-
+RC0 requires `nativewind@5.0.0-rc.0` and `react-native-css@3.1.0-rc.0` together. Check the resolved versions in your lockfile or with `npm ls nativewind react-native-css`. Use the equivalent command for your package manager.
 
-Before troubleshooting Nativewind, it's crucial to ensure that Tailwind CSS itself is functioning correctly. Nativewind uses the Tailwind CLI to compile your styles, so any issues with the Tailwind CLI should be resolved first. 
+After changing dependencies or configuration, restart Metro:
 
-Using the command `npx tailwindcss --input  --output output.css`, the Tailwind CLI will generate an `output.css` file. **The `` should be your project's main CSS file (typically `global.css` or `styles.css`) that contains the `@import 'tailwindcss';` directive.**
-
-For example:
 ```bash
-npx @tailwindcss/cli --input ./global.css --output output.css
+npx expo start --clear
 ```
 
-If you are troubleshooting a class that is not working, ensure that the CSS rule is present in the `output.css` file. This will help you determine if the issue is with Tailwind compilation or with Nativewind's runtime.
-
-## Verifying Nativewind Installation
-
-Nativewind provides a utility function `verifyInstallation()` designed to help confirm that the package has been correctly installed.
-
-Import the `verifyInstallation` function from the Nativewind package and run it within the scope of a React component. **Do not invoke this function on the global scope**; it should be run within a component.
+Rebuild native apps when native dependencies change. The tested target is Expo 57.0.22 with React Native 0.86.3, Reanimated 4.5.1 and Worklets 0.10.1. Align native packages with Expo rather than bypassing peer errors.
 
-```tsx
-import React from 'react';
-import { verifyInstallation } from 'nativewind';
+## Build succeeds but styles are missing
 
-function App() {
-    // Ensure to call inside a component, not globally
-    verifyInstallation();
+V5 compiles Tailwind 4 through `@tailwindcss/postcss`. Expo 57 discovers `postcss.config.js` or `postcss.config.mjs`, but not `postcss.config.cjs`. Check the [installation guide](/v5/getting-started/installation), root CSS import and Tailwind source discovery.
 
-    return (
-      // Your component JSX here...
-    );
-}
+For an isolated Tailwind check using the same tested version:
 
-export default App;
+```bash
+npx @tailwindcss/cli@4.1.12 --input ./global.css --output output.css
 ```
 
-## Enabling debug mode
-
-Nativewind supports the `DEBUG` environment variable and will output various debug information while your server is running. **Run this command in your project's root directory where your `package.json` file is located.**
-
-The `` should be replaced with your project's actual start command:
-
-- **Expo**: `npx expo start --clear`
-- **Framework-less React Native**: `npx react-native start --reset-cache`
-- **Next.js**: `npm run dev` or `yarn dev`
-- **Other frameworks**: Use your project's standard development start command
-
-
-  
-    ```bash
-    DEBUG=nativewind 
-    ```
-  
-  
-    ```cmd
-    set "DEBUG=nativewind" && 
-    ```
-  
-
-
-
-@react-native-community/cli may create multiple terminal sessions. You will need to ensure all sessions have `DEBUG=nativewind` set.
-
-
-By itself, this information may or may not be useful to you, but it is extremely useful when reporting issues to the developers on GitHub. You can record the terminal output by redirecting the output to a file.
-
-
-  
-    ```bash
-    DEBUG=nativewind script output.log 
-    ```
-  
-  
-    ```cmd
-    set "DEBUG=nativewind" && script output.log 
-    ```
-    
-    **Note:** For older Windows versions, use:
-    ```cmd
-    set "DEBUG=nativewind" &&  > output.log 2>output.log
-    ```
-    
-    **For PowerShell:**
-    ```powershell
-    $env:DEBUG="nativewind";  *> output.log
-    ```
-  
-
-
-## Common Issues
-
-### Your cache is loading old data
-
-Always reset your cache before troubleshooting an issue.
-
-### Colors are not working
-
-React Native styling is much more restrictive than the web. This code will work on the web, but not on React Native:
-
-```tsx title=App.tsx
-export function App() {
-  return (
-    
-      Hello, World!
-    
-  );
-}
-```
+Check that the expected utility exists in the output. This verifies Tailwind generation only; it does not verify Metro integration or native rendering.
+
+On web, use the split theme, preflight and unlayered utility imports from the installation guide. A single `@import "tailwindcss"` can let React Native Web default styles win over your utilities.
 
-The reason is that `` does not accept a `color` style and will not cascade the style! Instead, you must move the color classes to the `` element.
+## Legacy configuration errors
 
-### Modifiers are not working
+The RC rejects `@cssInterop`, `@react-native` configuration and qualified native root selectors such as `:root.dark`. Follow [Upgrade a v5 preview](/v5/guides/migrate-from-preview) to translate their intent. Do not suppress these errors.
 
-Ensure the component you are applying the style to supports both the style and the required props (e.g., `hover:text-white` - does the component support `color` styles and have an `onHover` prop?).
+`verifyInstallation`, `cssInterop` and `remapProps` are not Nativewind RC0 exports. Use [styled](/v5/api/styled) for component mapping and verify a visible styled element instead of calling the v4 installation helper.
 
-### Explicit styles
+## Runtime variables do not update
 
-React Native has various issues when conditionally applying styles. To prevent these issues, it's best to declare all styles explicitly.
+Use `VariableContextProvider` with its `value` prop. Preserve dynamic variables with `inlineVariables.exclude` in Metro options. See [Dynamic Themes](/v5/guides/themes).
 
-For example, instead of only applying a text color for dark mode, provide both a light and dark mode text color.
+## Theme changes do not apply
 
-### dp vs px
+Install `expo-system-ui`, set `expo.userInterfaceStyle` to `"automatic"`, and rebuild for native configuration changes. On the tested Expo 57 target, `Appearance.setColorScheme("unspecified")` restores system appearance. Browser manual theme controls need separate configuration. See [Dark Mode](/v5/core-concepts/dark-mode).
 
-React Native's default unit is density-independent pixels (dp) while the web's default is pixels (px). These two units are different; however, Nativewind treats them as if they are equivalent. Additionally, Nativewind's compiler requires a unit for most numeric values, forcing some styles to use a `px` unit.
+## Unsupported component props
 
-### Flex
+Adding a TypeScript declaration does not create a runtime mapping. Use supported native props or a `styled` wrapper for third party components. For TextInput placeholder color, use `className="placeholder:text-gray-500"`.
 
-React Native uses a different base flex definition than the web. This can be fixed by adding `flex-1` to your classes, which forces the platforms to align.
+## Platform differences and bug reports
 
-### Flex Direction
+Apply text colors to Text components rather than expecting them to cascade through View. Native `px` values become density independent points, and the default native `rem` is 14. Compare intended layouts on each supported platform.
 
-React Native uses a different default `flex-direction` than the web. This can be fixed by explicitly setting a `flex-direction`. 
+Check the [RC compatibility guide](https://github.com/nativewind/nativewind/blob/main/docs/rc-compatibility.md), including the Android animation cancellation limitation. When reporting an issue, include exact package versions, Expo SDK, platform and OS, development or release mode, configuration, expected and actual behavior, and a minimal reproduction. Note whether direct React Native or Reanimated reproduces it.
diff --git a/content/v5/getting-started/typescript.mdx b/content/v5/getting-started/typescript.mdx
index 049ede0..14fd7a5 100644
--- a/content/v5/getting-started/typescript.mdx
+++ b/content/v5/getting-started/typescript.mdx
@@ -7,7 +7,7 @@ title: Typescript
 Nativewind extends the React Native types via declaration merging. The simplest method to include the types is to create a new `nativewind-env.d.ts` file and add a [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) referencing the types.
 
 ```tsx
-/// 
+/// 
 ```
 
 
@@ -18,4 +18,5 @@ Do not call this file:
 - The same name as a folder in `node_modules`, e.g `react.d.ts`
 
 By doing so, your types will not be picked up by the TypeScript compiler.
-
\ No newline at end of file
+
+Ensure this declaration file is included by your tsconfig. If TypeScript reports an unresolved side effect CSS import, add `declare module "*.css";` to an application declaration file included by that project. Do not retain obsolete v4 declarations to silence missing RC props.
diff --git a/content/v5/guides/custom-components.mdx b/content/v5/guides/custom-components.mdx
index 212bee7..b8c56ec 100644
--- a/content/v5/guides/custom-components.mdx
+++ b/content/v5/guides/custom-components.mdx
@@ -1,13 +1,13 @@
 ---
 title: Writing Custom Components
 ---
-  
+
 {/* # Writing Custom Components */}
-  
+
 
 This guide is about writing your own components. If you are looking for a guide on how to use Nativewind with third-party components, see the [third-party components](./third-party-components) guide.
 
-Unless you are styling a custom native component, you should never have to use `cssInterop` or `remapProps` when writing your own components. These are only used when working with third-party components.
+Unless you are styling a custom native component, you should never have to use `styled` when writing your own components. These are only used when working with third-party components.
 
 
 ## Your first component
diff --git a/content/v5/guides/migrate-from-preview.mdx b/content/v5/guides/migrate-from-preview.mdx
new file mode 100644
index 0000000..8e1eca5
--- /dev/null
+++ b/content/v5/guides/migrate-from-preview.mdx
@@ -0,0 +1,42 @@
+---
+title: Upgrade a v5 preview
+---
+
+This guide covers Nativewind 5.0.0-preview.4 with react-native-css 3.0.7 to the v5 release candidate. Apps on Tailwind 3 need the [v4 migration](/v5/guides/migrate-from-v4).
+
+## Update the pair
+
+Preserve your source, manifests, lockfile and configuration, and capture working screens before updating. Use your existing package manager. For npm:
+
+```bash
+npm install --save-exact nativewind@5.0.0-rc.0 react-native-css@3.1.0-rc.0
+```
+
+RC0 requires the exact engine candidate. Keep working Tailwind 4, PostCSS and `withNativewind` configuration. Use the [split Tailwind imports](/v5/getting-started/installation) with unlayered utilities for React Native Web. Expo 57 requires a discovered PostCSS filename such as `postcss.config.mjs`, not `postcss.config.cjs`.
+
+Expo 57.0.22 with React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1 is the tested target. An older SDK upgrade needs separate verification.
+
+## Check changed contracts
+
+1. Legacy `@cssInterop` and `@react-native` configuration now reports explicit errors. Use Appearance for native theme selection and `inlineVariables.exclude` for runtime variables.
+2. Qualified root selectors such as `:root.dark` are rejected on native. Use `prefers-color-scheme` media queries. Preserve custom browser selectors separately.
+3. Unsupported prop declarations were removed: `placeholderClassName`, `indicatorClassName`, `presentationClassName`, `cssInterop` and StatusBar `className`. Use supported native props or [styled mappings](/v5/api/styled). TextInput placeholder color uses `placeholder:` utilities.
+4. Recheck workarounds for line height, ripple, corner styling and prop mappings against the RC before removing them.
+
+`vars()`, the deprecated Nativewind color scheme hook, `useUnstableNativeVariable` and the `nativeStyleToProp` alias are still available. They do not need to be replaced just to update the RC.
+
+## Migration skill
+
+```bash
+npx skills add nativewind/nativewind --skill nativewind-preview-to-rc
+```
+
+The [skill](https://github.com/nativewind/nativewind/tree/main/skills/nativewind-preview-to-rc) checks the starting state, including interrupted upgrades, and records remaining verification. Its fixture tests do not replace checks in your application.
+
+## Verify the result
+
+Restart Metro after replacing the engine. Rebuild if native dependencies or configuration change. Check dependency alignment, types, production bundles and actual screens on each supported platform, including input, navigation, themes and animations. On the tested native target, `Appearance.setColorScheme("unspecified")` restores system appearance after an override.
+
+See the [RC compatibility guide](https://github.com/nativewind/nativewind/blob/main/docs/rc-compatibility.md) for platform limits. Android animation cancellation has a known upstream issue. Keep unavailable checks marked as pending.
+
+To revert, restore only this migration's source, manifest, lockfile and configuration changes from the snapshot, reinstall, and rebuild if needed.
diff --git a/content/v5/guides/migrate-from-v4.mdx b/content/v5/guides/migrate-from-v4.mdx
index 6b2091e..ded409a 100644
--- a/content/v5/guides/migrate-from-v4.mdx
+++ b/content/v5/guides/migrate-from-v4.mdx
@@ -2,435 +2,108 @@
 title: Migrate from v4
 ---
 
-import { Callout } from "@/components/callout";
 import { CopyMigrationButton } from "@/components/copy-migration-button";
 
-

-  
-

+
 
-## Migration steps
+## Choose the migration path
 
-The simplest way to migrate from Nativewind v4 to v5 is to follow these steps:
+This guide targets Nativewind 5.0.0-rc.0 and react-native-css 3.1.0-rc.0 from Nativewind v4, including v4.2.7. V4 remains stable and uses Tailwind CSS 3. If you are already on v5 preview.4, follow [Upgrade a v5 preview](/v5/guides/migrate-from-preview).
 
-### Step 1: Update Dependencies
+The RC was tested with Expo 57.0.22, React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1. Upgrade and verify an older Expo SDK separately. Do not force native dependency versions just to satisfy a styling migration.
 
-Install the new versions of required packages:
+NativewindUI v4 components should remain on Nativewind v4. Use their supported v4 setup instead of partially converting them to v5.
 
-```bash
-# Using Expo CLI (recommended)
-npx expo install nativewind@preview react-native-css@latest react-native-reanimated react-native-safe-area-context
-
-# Install Tailwind CSS v4 and PostCSS as dev dependencies
-npx expo install --dev tailwindcss @tailwindcss/postcss postcss
-```
-
-### Step 2: Update CSS File
-
-Replace your old CSS directives with the new Tailwind v4 imports in your `global.css` (or equivalent):
-
-```diff
-- @tailwind base;
-- @tailwind components;
-- @tailwind utilities;
-
-+ @import "tailwindcss/theme.css" layer(theme);
-+ @import "tailwindcss/preflight.css" layer(base);
-+ @import "tailwindcss/utilities.css";
-+
-+ @import "nativewind/theme";
-```
-
-### Step 3: Update Babel Config
-
-Remove Nativewind from your `babel.config.js`:
-
-```diff
-module.exports = function (api) {
-  api.cache(true);
-  return {
-    presets: [
--      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
--      "nativewind/babel",
-+      "babel-preset-expo",
-    ],
-  };
-};
-```
-
-### Step 4: Create PostCSS Config
-
-Create a `postcss.config.mjs` file in the root of your project:
-
-```javascript
-// postcss.config.mjs
-export default {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-};
-```
-
-### Step 5: Update Metro Config
-
-Update the `withNativewind` function call (no longer requires a second argument):
-
-```diff
-- module.exports = withNativeWind(config, { input: './global.css' })
-+ module.exports = withNativewind(config);
-```
-
-Note: While `withNativeWind` was renamed to `withNativewind`, either will work.
-
-### 6. Override the lightningcss version
-
-Force `lightningcss` to a specific version in your `package.json`:
-
-
-  
-    ```json title="package.json"
-    {
-      "overrides": {
-        "lightningcss": "1.30.1"
-      }
-    }
-    ```
-  
-  
-    ```json title="package.json"
-    {
-      "resolutions": {
-        "lightningcss": "1.30.1"
-      }
-    }
-    ```
-  
-  
-    ```json title="package.json"
-    {
-      "pnpm": {
-        "overrides": {
-          "lightningcss": "1.30.1"
-        }
-      }
-    }
-    ```
-  
-  
-    ```json title="package.json"
-    {
-      "overrides": {
-        "lightningcss": "1.30.1"
-      }
-    }
-    ```
-  
-
-
-
-  If you don't pin the `lightningcss` version, you may encounter deserialization errors with respect to `global.css` when building your app.
-
-
-### Step 7: Clear Cache and Restart
+## Use the migration skill
 
 ```bash
-npx expo start --clear
+npx skills add nativewind/nativewind --skill nativewind-v4-to-v5
 ```
 
-You should now be running Nativewind v5 🎉
-
-### Troubleshooting Common Issues
-
-If you encounter issues, here are some common problems and solutions:
-
-**JSX Transform Errors**: Ensure you removed `nativewind` from your babel config and cleared the Metro cache with `npx expo start --clear`.
-
-**Incorrect CSS atRules**: Verify you updated to the new atRules in your CSS file (see Step 2 above).
-
-**Metro Config Issues**: The `withNativewind` function no longer requires a second argument. Ensure your config matches Step 5.
-
-**Missing PostCSS Config**: Ensure the `postcss.config.mjs` file was created with the correct content.
-
-## Breaking Changes & Prerequisites
-
-Before upgrading to Nativewind v5, your project **must** meet the following version requirements:
-
-### Tailwind CSS v4.1+
-
-Nativewind v5 is built on top of Tailwind v4.1+. You must upgrade your Tailwind configuration and tooling, accordingly.
-
-
-  **Migration Tip:** Refer to the [Tailwind CSS v4 Upgrade
-  Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed steps.
-
-
-### React Native 0.81+
-
-React Native 0.81 introduces architectural changes that Nativewind v5 relies on, including improvements to the StyleSheet and layout engines.
-
-> Use `react-native upgrade` or migrate your setup manually to update.
-
-
-
-Earlier versions of React Native can work, albeit with limited functionality. Nativewind only provides support for React Native 0.81+.
-
-
-
-### React Native New Architecture
-
-A number of styles require the new architecture.
-
-
-
-The old architecture can work with limited functionality. However, we only provide support for the new React Native architecture.
-
-
-
-### React Native Reanimated v4+
-
-Nativewind v5 uses internal features that depend on Reanimated v4+. Ensure your project uses this version to avoid runtime crashes or build issues.
-
-> **Note:** Reanimated v4 introduces its own breaking changes — please consult the [Reanimated v4 changelog](https://docs.swmansion.com/react-native-reanimated/) when upgrading.
-
-### React Native CSS
-
-Nativewind previously used a transient dependency on a library called `react-native-css-interop`. This library has been renamed to `react-native-css`, has been moved to be a peer dependency, and will require separate installation.
-
-Nativewind will no longer be tied to a specific version of `react-native-css` and the two libraries can be updated individually.
-
-## Breaking changes
-
-### Tailwind CSS changes
-
-Please ensure you are familiar with the [Tailwind CSS upgrade guide](https://tailwindcss.com/docs/upgrade-guide). It has a number of breaking changes, renamed styles and deprecations.
-
-### Classname changes
-
-Tailwind v4 changed the standard for its classnames. As such, these Nativewind classes have also been renamed:
-
-- `elevation-sm` has been renamed to `elevation-xs`
-- `elevation` has been renamed to `elevation-sm`
-
-### Animation changes
-
-Nativewind has switched from using a custom animation engine to Reanimated CSS animations. You may find there are implementation differences between the two engines.
-
-### JavaScript Theme Functions
-
-The JavaScript theme functions have been removed and replaced with CSS equivalent functions. Please see the [Tailwind CSS functions and directives](https://tailwindcss.com/docs/functions-and-directives#functions) documentation for more information.
-
-### `shadow-*`
-
-The `shadow-*` classes now use `boxShadow` style. Previously they used `shadowColor`, `shadowOffset`, `shadowOpacity` and `shadowRadius`. There may be a visual difference.
-
-### Line Height
-
-Line height numeric values are parsed as if they had the `em` unit. Previously they were parsed as a unit-less value. To migrate, simply divide the old value by the font-size.
+Ask your agent to apply the skill to your app. It includes a read only preflight, checks for custom configuration and component mappings, and recovery instructions. Review the [skill and measured verification scope](https://github.com/nativewind/nativewind/tree/main/skills/nativewind-v4-to-v5). Fixture results do not establish that every application is verified.
 
-### rem
+## 1. Preserve a working baseline
 
-`rem` is no longer exported and cannot be changed at runtime. If you require Tailwind CSS to dynamically change values, you should update your theme to use a CSS variable instead of `rem`
+Work on a branch. Preserve your source, package manifests, lockfile and configuration, including any uncommitted work. Record the package manager and exact starting versions. Capture representative screens and interactions before editing, including themes, animations, navigation and third party components.
 
-### Dynamic mapping modifier
+## 2. Update the dependency group together
 
-The dynamic mapping modifier has been renamed to `@prop`.
+Update Nativewind, its engine and Tailwind/PostCSS together in your manifest before installing with your existing package manager:
 
-```diff
-- {}-[inputColor]:color-black
-+ @prop-[inputColor]:color-black
-```
-
-### `vars()` → Replaced by `VariableContextProvider`
-
-The `vars()` function for dynamic theming is deprecated. Use the `VariableContextProvider` component instead:
-
-```diff
-- import { vars } from "nativewind";
-+ import { VariableContextProvider } from "nativewind";
-
-- const theme = vars({ "--color-primary": "red" });
-
-- 
--   {children}
-- 
-
-+ 
-+   {children}
-+ 
-```
-
-See the [Dynamic Themes](/v5/guides/themes) guide for full examples.
-
-## Deprecations
-
-Nativewind v5 preserves its existing API. Your usage of:
-
-- `className`
-- `styled`
-
-...will continue to work without modification.
-
-However, several features are being **deprecated** and will emit runtime warnings during development. These features will be **removed in a future major release**.
-
-
-  **Warning:** Deprecated features will continue to function in v5 but should be
-  migrated away from as soon as possible.
-
-
-However, there will be a number of breaking changes to how Nativewind functions and its configuration file that may affect you.
-
-## JSX Transform → Replaced by Import Rewrites
-
-Nativewind v5 **removes the JSX transform** that previously injected Tailwind support into individual JSX elements. This has been replaced by a new **import rewrite system**.
-
-This does not require any configuration change, but may affect your app if you are performing your own import rewrites. Previously Nativewind would change this code:
-
-```jsx
-import { View, Text } from "react-native";
-
-
-  Hello
-;
-```
-
-Now the `import` will be rewritten to `import { View, Text } from 'react-native-css/react-native'`
-
-The move to import rewrites is driven by a broader shift in the React Native ecosystem of publishing compiled libraries. Nativewind previously took advantage of the fact that libraries were always compiled locally, which allowed us to override the `jsxImportSource`. When libraries are compiled externally, their JSX is already transformed. The new shift to import rewrites is similar to how existing libraries such as `react-native-web` work.
-
-## `cssInterop` / `remapProps` → Replaced by `styled()`
-
-The `cssInterop` and `remapProps` APIs are deprecated and have been replaced with a unified `styled` API. It accepts the same options as `cssInterop`/`remapProps` and returns the same component. The `remapProps` mode is available via a new 3rd parameter:
-
-```jsx
-// Same as cssInterop()
-styled(View, { className: "style" });
-
-// Same as remapProps()
-styled(View, { className: "style" }, { passThrough: true });
-```
-
-By default `styled()` enables the transform globally for that component, but this can be disabled by setting `global` to false:
-
-```jsx
-const MyComponent = styled(View, { className: "style" }, { global: false });
-```
-
-## Native functions
-
-The `nativewind/theme` export has been removed. You can now access these functions as CSS functions.
-
-### `platformColor`
-
-`platformColor()` is available as a CSS function:
-
-```css
-@theme {
-  --color-error: platformColor(systemRed, red);
+```json
+{
+  "dependencies": {
+    "nativewind": "5.0.0-rc.0",
+    "react-native-css": "3.1.0-rc.0"
+  },
+  "devDependencies": {
+    "tailwindcss": "4.1.12",
+    "@tailwindcss/postcss": "4.1.12",
+    "lightningcss": "1.30.1"
+  }
 }
 ```
 
-### `hairlineWidth`
+Merge these entries into your existing manifest; do not replace it. Install PostCSS as shown in the [installation guide](/v5/getting-started/installation), and let `npx expo install` align Reanimated, Worklets, safe area context and expo-system-ui with your SDK.
 
-`hairlineWidth()` is available as a CSS function:
+Nativewind RC0 requires the exact engine candidate above. The packages cannot be upgraded independently for this release. Remove direct `react-native-css-interop` dependencies only after checking that no application or workspace consumer still needs them.
 
-```css
-@theme {
-  --spacing-hairline: hairlineWidth();
-}
-```
+If npm reports `ERESOLVE` from the stale v4/Tailwind 3 graph, do not use `--force` or `--legacy-peer-deps`. Follow the [tested recovery procedure](https://github.com/nativewind/nativewind/blob/main/skills/nativewind-v4-to-v5/references/installation.md), which saves the intended manifest and lets npm update the styling dependency group without deleting the lockfile. Workspaces require a consumer inventory first.
 
-### `pixelRatio`
+## 3. Convert Tailwind configuration
 
-`pixelRatio()` is available as a CSS function:
+Translate custom theme values, plugins and utilities to Tailwind 4 CSS configuration. Preserve any customizations that do not have a verified replacement. Review the [Tailwind upgrade guide](https://tailwindcss.com/docs/upgrade-guide); utility renames alone do not prove the same native appearance.
 
-```css
-@theme {
-  --spacing-doublePixelRatio: calc(pixelRatio(2) * 2);
-}
+Replace the Tailwind 3 directives in your root CSS:
+
+```css title="global.css"
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css";
+@import "nativewind/theme";
 ```
 
-### `fontScale`
+Keep utilities unlayered so React Native Web defaults do not override them. Add `@source` paths for shared workspace components when needed.
 
-`fontScale()` is available as a CSS function:
+Create or update `postcss.config.mjs`, preserving unrelated plugins:
 
-```css
-@theme {
-  --spacing-doubleFontScale: calc(fontScale(2) * 2);
-}
+```js title="postcss.config.mjs"
+export default { plugins: { "@tailwindcss/postcss": {} } };
 ```
 
-### `getPixelSizeForLayoutSize`
-
-`getPixelSizeForLayoutSize()` is available as a CSS function:
+Expo 57 does not discover `postcss.config.cjs`. Follow the installation guide to pin lightningcss 1.30.1 through your package manager's overrides or resolutions.
 
-```css
-@theme {
-  --spacing-custom: getPixelSizeForLayoutSize(42);
-}
-```
+## 4. Update Babel, Metro and TypeScript
 
-### `roundToNearestPixel`
+Remove `nativewind/babel` and the Nativewind `jsxImportSource` setting from the v4 setup. Keep `babel-preset-expo` and unrelated plugins.
 
-`roundToNearestPixel()` is available as a CSS function:
+```js title="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { withNativewind } = require("nativewind/metro");
 
-```css
-@theme {
-  --spacing-custom: roundToNearestPixel(calc(10 / 3));
-}
+module.exports = withNativewind(getDefaultConfig(__dirname));
 ```
 
-### `platformSelect`
+Wrap your existing Metro config rather than discarding custom resolvers. The v4 `input` option is no longer needed. Import the root CSS once in `App.tsx` or `app/_layout.tsx`. Ensure the generated `nativewind-env.d.ts` belongs to your TypeScript project.
 
-Now use a media query that sets the platform as the media type:
+## 5. Review application contracts
 
-```css
-@theme {
-  --color-error: var(--my-color, green);
-}
+Use [styled](/v5/api/styled) for components that need explicit mapping. The RC does not export `cssInterop` or `remapProps` from Nativewind. Do not mechanically rename those functions: `styled` returns a wrapper that must be used, and prop destinations and precedence need to be checked. There is no `global` option. `nativeStyleMapping` is the current mapping option; `nativeStyleToProp` remains a deprecated alias.
 
-@media ios {
-  :root {
-    --my-color: red;
-  }
-}
+For native theme overrides, use `Appearance.setColorScheme("dark")` or `"light"`. On the Expo 57 target, `"unspecified"` restores system appearance. Set `expo.userInterfaceStyle` to `"automatic"`. Preserve any custom browser theme selection separately. See [Dark Mode](/v5/core-concepts/dark-mode).
 
-@media android {
-  :root {
-    --my-color: blue;
-  }
-}
-```
+Prefer [VariableContextProvider](/v5/guides/themes) for runtime variables and exclude variables that must remain dynamic from compiler inlining. Cross platform lengths need units, for example `"80px"`. `vars()`, the Nativewind color scheme hook and `useUnstableNativeVariable` remain available; deprecated does not mean removed.
 
-### `pixelRatioSelect` / `fontScaleSelect`
+Remove legacy `@cssInterop` or `@react-native` configuration after translating its intent. Qualified native root selectors such as `:root.dark` are rejected; use media queries and Appearance on native.
 
-Now use a media query:
+Props such as `placeholderClassName`, `indicatorClassName`, `presentationClassName`, `cssInterop` and StatusBar `className` no longer have declarations for unsupported v5 mappings. Use native props or explicit supported wrappers. TextInput supports `className="placeholder:text-gray-500"`.
 
-```css
-@theme {
-  --spacing-custom-pixel: 11;
-  --spacing-custom-font: 11;
-}
-
-@media (pixelRatio() > 2) {
-  :root {
-    --spacing-custom-pixel: 3;
-  }
-}
+Shadows now use React Native `boxShadow`, and animations use Reanimated CSS animations. Compare the affected screens with your baseline. See the [RC compatibility guide](https://github.com/nativewind/nativewind/blob/main/docs/rc-compatibility.md) for value and platform limits, including the known Android animation cancellation issue.
 
-@media (fontScale() > 2) {
-  :root {
-    --spacing-custom-font: 3;
-  }
-}
-```
+## 6. Verify and recover
 
-## New CSS Features
+Restart Metro with `npx expo start --clear`. Rebuild native apps when native dependencies or configuration change. Run typechecks and production bundles, then compare actual rendering and interactions on every supported platform. Include theme override and system restoration, mappings, text entry, navigation and animations.
 
-Nativewind v5 adds support for the new React Native styling features:
+A successful export does not prove visual parity. Report unavailable or failing runtime checks as verification pending. A second migration pass should make no new source or dependency changes.
 
-- `position: static` ([Tailwind](https://tailwindcss.com/docs/position)) ([Yoga](https://www.yogalayout.dev/blog/announcing-yoga-3.0#position-static))
-- `align-content: space-evenly` ([Tailwind](https://tailwindcss.com/docs/place-content#space-evenly)) ([Yoga](https://www.yogalayout.dev/blog/announcing-yoga-3.0#better-support-for-multiline-containers))
-- `filter()` ([Tailwind](https://tailwindcss.com/docs/filter)) ([React Native](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture#box-shadow-and-filter-style-props))
-- `backgroundImage()` ([Tailwind](https://tailwindcss.com/docs/background-image)) (gradients only)
-- `box-sizing` ([Tailwind](https://tailwindcss.com/docs/box-sizing))
-- `display: contents` ([Tailwind](https://tailwindcss.com/docs/display#contents))
+To revert, restore only this migration's changes from your source, manifest, lockfile and configuration snapshots. Reinstall with the same package manager and rebuild if native dependencies changed. Preserve unrelated user work.
diff --git a/content/v5/guides/themes.mdx b/content/v5/guides/themes.mdx
index 0d59b02..b6671b5 100644
--- a/content/v5/guides/themes.mdx
+++ b/content/v5/guides/themes.mdx
@@ -43,6 +43,21 @@ First, define your theme variables in CSS:
   You need to define the variables in both `@theme` (so Tailwind generates the utility classes) and `:root` (so the CSS variables have default values at runtime).
 
 
+Preserve each variable you override at runtime from native compiler inlining:
+
+```js title="metro.config.js"
+const { getDefaultConfig } = require("expo/metro-config");
+const { withNativewind } = require("nativewind/metro");
+
+module.exports = withNativewind(getDefaultConfig(__dirname), {
+  inlineVariables: {
+    exclude: ["--color-primary", "--color-secondary"],
+  },
+});
+```
+
+Add other dynamic tokens to this list, including `--color-foreground` and `--color-muted-foreground` in the multiple themes example below. Use units for cross platform length variables, such as `"80px"`.
+
 Then override them at runtime:
 
 ```tsx title="App.tsx"
@@ -114,7 +129,8 @@ export function ThemeProvider({
   name: keyof typeof themes;
   children: React.ReactNode;
 }) {
-  const colorScheme = useColorScheme() ?? "light";
+  const appearance = useColorScheme();
+  const colorScheme = appearance === "dark" ? "dark" : "light";
 
   return (
     
@@ -126,6 +142,7 @@ export function ThemeProvider({
 
 ```tsx title="app/_layout.tsx"
 import "../global.css";
+import { Stack } from "expo-router";
 import { ThemeProvider } from "@/components/ThemeProvider";
 
 export default function RootLayout() {
@@ -153,7 +170,7 @@ export default function RootLayout() {
 
 ## Migrating from v4
 
-If you used `vars()` in v4, replace it with `VariableContextProvider`:
+`vars()` remains available but deprecated in RC0. For new code or a planned refactor, use `VariableContextProvider`:
 
 ```diff
 - import { vars } from "nativewind";
diff --git a/content/v5/guides/third-party-components.mdx b/content/v5/guides/third-party-components.mdx
index dee0bf8..287c5a1 100644
--- a/content/v5/guides/third-party-components.mdx
+++ b/content/v5/guides/third-party-components.mdx
@@ -1,227 +1,63 @@
 ---
-title: "Styling Third-Party Components"
+title: Styling Third Party Components
 ---
 
-{/* # Styling third-party components */}
+Components that forward `className` to a supported React Native component can use Nativewind directly. Components that consume only a `style` prop or require individual style values as props need an explicit [styled](/v5/api/styled) wrapper.
 
-A third-party component is a component that is a dependency of your application and not a core React Native component. Nativewind works by passing the `className` prop to the core React Native components. Unfortunately, its not always obvious what third-party components implement this behavior without checking their source code.
-
-This is an example of a 3rd party component that does not pass the `className` prop down:
-
-```tsx
-// ❌ This component will not work with Nativewind
-// This component is 'picking' the props.
-// Any props that are not explicitly defined will not be passed down
-function ThirdPartyComponent({ style }) {
-  return ;
-}
-
-// ✅ This component will work with Nativewind
-function ThirdPartyComponent({ style, ...props }) {
-  return ;
-}
-```
-
-## Improving 3rd party components
-
-If you encounter a 3rd party component 'picks' its props, you should consider submitting a pull request to modify the component so it passes all props down. Components that 'pick' their props can be very limiting, and not just for Nativewind! React Native often adds new APIs and 'picking' props prevents you from using these new features.
-
-```tsx
-function ThirdPartyComponent({ style }) {
-  return ;
-}
-
-// aria-label was added in 0.71, but this component will not work with it!
-;
-```
-
-## Handling components with multiple style props
-
-Some components will pass the `className` prop down, but they may also have multiple style props. For example, React Native's `` component has a `style` and `contentContainerStyle` prop. The `remapProps` function can be used to create new `className` props for these components.
+## Map className to styles
 
 ```tsx
-// This component has two 'style' props
-function ThirdPartyComponent({ style, contentContainerStyle, ...props }) {
-  return (
-    
-  );
-}
+import { styled } from "nativewind";
+import { ThirdPartyView } from "third-party-library";
 
-// Call this once at the entry point of your app
-remapProps(ThirdPartyComponent, {
-  className: "style",
-  contentContainerClassName: "contentContainerStyle",
-});
+const StyledView = styled(ThirdPartyView, { className: "style" });
 
-// Now you can use the component with Nativewind
-;
+;
 ```
 
-
-Nativewind's style objects are more complex than the objected created `StyleSheet.create`. To not break third-party components, `remapProps` will pass a special object to the target prop. To the third-party component this will appear as an empty object.
-
+Render `StyledView`, the returned component. The original component is unchanged. Define wrappers outside your render function to preserve component identity.
 
-## Handling components with style attribute props
+## Map styles to component props
 
-Some components may require style attributes to be passed as props (for example, React Native's `` component accepts a `backgroundColor` prop), or they may access the `style` prop directly.
+The following component reads a color prop rather than forwarding className:
 
 ```tsx
-/*
- * This component will not work as expected with Nativewind
- *   - borderColor will not work as it is a prop
- *   - backgroundColor will not work as it is based on the style.color value
- */
-function ThirdPartyComponent({ borderColor, style, ...props }) {
-  // The background color is based on the style prop
-  const backgroundColor = style.color === "white" ? "black" : "white";
-  return (
-    
-  );
-}
-```
-
-To support these components, you can use the [`cssInterop`](./../api/css-interop) function. You can think of `cssInterop` as a "className termination". It a marker that Nativewind needs to convert the `className` props into style objects.
-
-
-Enabling the `cssInterop` for a component comes at a performance cost. Nativewind will need to resolve the styles, add event handlers, inject context, etc.
-
-
-## Handling multiple props with similar properties
-
-Sometimes a component will have multiple props that are similar.
+import { View } from "react-native";
+import { styled } from "nativewind";
 
-```tsx
-function ThirdPartyComponent({ labelColor, inputColor, ...props }) {
-  return (
-    <>
-      Label
-      
-    
-  );
+function GaugeBase({ color }: { color?: string }) {
+  return ;
 }
-```
-
-You could creating a new mapping for each props, but it can be cumbersome to manage multiple props with className management libraries
-
-```tsx
-// This is possible
-cssInterop(ThirdPartyComponent, {
-  labelColorClassName: {
-    target: false
-    nativeStyleToProps: { color: 'labelColor' }
-  }
-  inputColorClassName: {
-    target: false
-    nativeStyleToProps: { color: 'inputColor' }
-  }
-})
-
-function Wrapper() {
-  // Need to create a new className for each prop
-  const labelStyle = cva('color-black')
-  const inputStyle = cva('color-black')
-
-  return (
-    
-  )
-}
-```
 
-Instead, you can use the dynamic mapping modifier to move props.
-
-```tsx
-cssInterop(ThirdPartyComponent, {
-  className: "style",
+const Gauge = styled(GaugeBase, {
+  className: {
+    target: false,
+    nativeStyleMapping: { color: true },
+  },
 });
 
-function Wrapper() {
-  // Need to create a new className for each prop
-  const style = cva("{}-[inputColor]:color-black {}-[labelColor]:color-black");
-
-  return ;
-}
+;
 ```
 
-## Dynamic mapping modifier
-
-The dynamic mapping modifier allows you to move props from one prop to another. This is useful when you have multiple props that are similar, or you want to manage the styles in a single prop.
+`target: false` omits a style destination. `color: true` sends the resolved color to the component's `color` prop. A string destination can rename it, for example `nativeStyleMapping: { color: "labelColor" }` for a component that accepts `labelColor`.
 
-There are two ways to use the dynamic mapping modifier:
+Explicit meaningful props can take precedence over generated props. Check both class derived values and explicit overrides in your application.
 
-- `{}-[]`: This will move the values the style to the `propName` prop. If a className sets multiple properties, the last property will be used.
-- `{}-[]:style-property`: This will move the `propName` prop to the `style-property` of the `className` prop, but only for the specified `style-property`
+## Components with multiple style props
 
-Both `propName` and `style-property` can be written using dot notation to access nested properties.
+Map each class prop to the corresponding supported style prop:
 
 ```tsx
-//This class
-{}-[screenOptions.tabBarTintColor]/color:color-red-500
-// Will output
-{ screenOptions: { tabBarTintColor: 'color-red-500' } }
-```
-
-## TypeScript
-
-Both `remapProps` and `cssInterop` will return a typed version of your component. However, you can globally defined the types in a new declaration file.
-
-```tsx title=custom-components-env.d.ts
-declare module "<3rd party package>" {
-  interface 3rdPartyComponentProps {
-    customClassName?: string;
-  }
-}
+const StyledList = styled(ThirdPartyList, {
+  className: "style",
+  contentContainerClassName: "contentContainerStyle",
+});
 ```
 
-**Example**
-
-Setting global types requires in-depth knowledge of TypeScript. Your interface declaration needs to **exactly match** the 3rd party declaration (including `extends` and generics).
+For components that forward styles to another styled consumer, the optional third argument `{ passThrough: true }` can defer resolution. Verify the downstream consumer supports it before using it.
 
-For example, Nativewind uses the follow types for React Native's ``, which uses multiple interfaces for its props, across multiple packages.
+## TypeScript and migration
 
-```tsx title=custom-components-env.d.ts
-import {
-  ScrollViewProps,
-  ScrollViewPropsAndroid,
-  ScrollViewPropsIOS,
-  Touchable,
-  VirtualizedListProps,
-} from "react-native";
+Use the typed wrapper returned by `styled`. Adding a declaration for an unsupported prop does not implement its runtime mapping. In RC0, props such as `indicatorClassName` and `presentationClassName` are not built in mappings. Use the underlying native prop or an explicitly supported wrapper.
 
-declare module "@react-native/virtualized-lists" {
-  export interface VirtualizedListWithoutRenderItemProps
-    extends ScrollViewProps {
-    ListFooterComponentClassName?: string;
-    ListHeaderComponentClassName?: string;
-  }
-}
-
-declare module "react-native" {
-  interface ScrollViewProps
-    extends ViewProps,
-      ScrollViewPropsIOS,
-      ScrollViewPropsAndroid,
-      Touchable {
-    contentContainerClassName?: string;
-    indicatorClassName?: string;
-  }
-  interface FlatListProps extends VirtualizedListProps {
-    columnWrapperClassName?: string;
-  }
-  interface ViewProps {
-    className?: string;
-  }
-}
-```
\ No newline at end of file
+The v4 `cssInterop` and `remapProps` exports are not available from Nativewind RC0. `nativeStyleToProp` remains a deprecated alias for `nativeStyleMapping`, but there is no `global` option. Preserve component identity, verify nested destinations and test native and browser behavior when migrating.
diff --git a/content/v5/guides/using-with-monorepos.mdx b/content/v5/guides/using-with-monorepos.mdx
index 2a30179..6ee2b8f 100644
--- a/content/v5/guides/using-with-monorepos.mdx
+++ b/content/v5/guides/using-with-monorepos.mdx
@@ -22,15 +22,25 @@ Simply configure your Expo project in Nx as per [the Expo setup guide](../gettin
 Add the Nativewind plugin to your `metro.config.js` using a promise chain as shown below:
 
 ```js title="metro.config.js"
-const { withNativeWind } = require("nativewind/metro");
+const { withNativewind } = require("nativewind/metro");
 
 // ... existing Nx configuration
 
 module.exports = withNxMetro(mergeConfig(defaultConfig, customConfig), {
   // ... existing Nx config
-}).then((config) => withNativeWind(config));
+}).then((config) => withNativewind(config));
 ```
 
+## Shared source files
+
+Tailwind must see classes from shared packages. Add paths relative to the CSS file, for example:
+
+```css
+@source "../../packages/ui/src";
+```
+
+Keep existing Nx/Metro resolver settings and inspect sibling consumers before removing v4 dependencies from a workspace. Verify shared component styles in native and web output.
+
 ## Additional Resources
 
 For more complex monorepo setups or specific issues, refer to:
diff --git a/content/v5/index.mdx b/content/v5/index.mdx
index 4948146..307ab80 100644
--- a/content/v5/index.mdx
+++ b/content/v5/index.mdx
@@ -4,6 +4,8 @@ title: Overview
 
 {/* # Overview */}
 
+Nativewind v5 is a release candidate. Start with the [RC installation](/v5/getting-started/installation), [v4 migration](/v5/guides/migrate-from-v4), or [preview upgrade](/v5/guides/migrate-from-preview). For the stable Tailwind 3 release, see [v4.2.7 docs](/docs).
+
 ## What is Nativewind?
 
 Nativewind allows you to use [Tailwind CSS](https://tailwindcss.com) to style your components in React Native. Styled components can be shared between all React Native platforms, using the best style engine for that platform; CSS StyleSheet on web and StyleSheet.create for native. Its goals are to provide a consistent styling experience across all platforms, improving Developer UX, component performance and code maintainability.
@@ -18,13 +20,13 @@ On web, Nativewind is a small polyfill for adding `className` support to React N
 
 🖥️ **DevUX** Plugins for simple setup and improving intellisense support
 
-✨ **Media & Container queries** Use modern mobile styling features like media and container queries [(docs)](../core-concepts/states#hover-focus-and-active)
+✨ **Media & Container queries** Use modern mobile styling features like media and container queries [(docs)](/v5/core-concepts/states#hover-focus-and-active)
 
 👪 **Custom values (CSS Variables)** Create themes, sub-themes and dynamic styles using custom values
 
-✨ **Pseudo classes** hover / focus / active on compatible components [(docs)](../core-concepts/states#hover-focus-and-active)
+✨ **Pseudo classes** hover / focus / active on compatible components [(docs)](/v5/core-concepts/states#hover-focus-and-active)
 
-👪 **Parent state styles** automatically style children based upon parent pseudo classes [(docs)](../core-concepts/states#hover-focus-and-active#styling-based-on-parent-state)
+👪 **Parent state styles** automatically style children based upon parent pseudo classes [(docs)](/v5/core-concepts/states#styling-based-on-parent-state)
 
 🔥 **Lots of other features**
 
@@ -50,16 +52,16 @@ On the web, it avoids injecting a StyleSheet at runtime by reusing the existing
 
 ## In action
 
-Nativewind handles both the Tailwind CSS compilation and the runtime styles. It works via a JSX transform, meaning there is no need for custom wrappers/boilerplate.
+Nativewind handles both the Tailwind CSS compilation and the runtime styles. Metro applies import rewrites for supported React Native components.
 
-As all React components are transformed with JSX, it works with 3rd party modules.
+Third party components may need an explicit `styled` wrapper if they do not forward className.
 
 ```tsx
 import { CustomText } from "third-party-text-component";
 
 export function BoldText(props) {
   // You just need to write `className=""`
-  return ;
+  return ;
 }
 ```
 
@@ -79,71 +81,4 @@ export function MyText({ bold, italic, lineThrough, ...props }) {
 }
 ```
 
-By default Nativewind maps `className`->`style`, but it can handle the mapping of complex components.
-
-```tsx
-remapProps(FlatList, {
-  className: "style",
-  ListFooterComponentClassName: "ListFooterComponentStyle",
-  ListHeaderComponentClassName: "ListHeaderComponentStyle",
-  columnWrapperClassName: "columnWrapperStyle",
-  contentContainerClassName: "contentContainerStyle",
-});
-
-
-```
-
-And can even work with components that expect style attributes as props
-
-```tsx
-import { Text } from "react-native";
-import { cssInterop } from "nativewind";
-import { Svg, Circle } from "react-native-svg";
-
-/**
- * Svg uses `height`/`width` props on native and className on web
- */
-const StyledSVG = cssInterop(Svg, {
-  className: {
-    target: "style",
-    nativeStyleToProp: {
-      height: true,
-      width: true,
-    },
-  },
-});
-/**
- * Circle uses `fill`/`stroke`/`strokeWidth` props on native and className on web
- */
-const StyledCircle = cssInterop(Circle, {
-  className: {
-    target: "style",
-    nativeStyleToProp: {
-      fill: true,
-      stroke: true,
-      strokeWidth: true,
-    },
-  },
-});
-
-export function BoldText(props) {
-  return (
-    
-      
-    
-  );
-}
-```
+For components that need explicit mapping, use the returned [styled wrapper](/v5/api/styled). Nativewind RC0 does not export the v4 `cssInterop` or `remapProps` functions. See [third party components](/v5/guides/third-party-components) for style and prop mapping examples.
diff --git a/content/v5/meta.json b/content/v5/meta.json
index f159929..f3f2998 100644
--- a/content/v5/meta.json
+++ b/content/v5/meta.json
@@ -15,6 +15,7 @@
 
     "---Guides---",
     "guides/migrate-from-v4",
+    "guides/migrate-from-preview",
     "guides/using-with-monorepos",
     "guides/custom-components",
     "guides/third-party-components",
diff --git a/content/v5/tailwind/_compatibility.mdx b/content/v5/tailwind/_compatibility.mdx
index 82697ea..b6d365d 100644
--- a/content/v5/tailwind/_compatibility.mdx
+++ b/content/v5/tailwind/_compatibility.mdx
@@ -4,6 +4,8 @@ title: _compatibility.mdx
 
 import Legend from "./_legend.mdx";
 
+
Support applies to the documented values and platforms. See the RC compatibility notes for value limits and native migration alternatives. Browser behavior is evaluated separately.

+
 
@@ -17,7 +19,7 @@ import Legend from "./_legend.mdx";
             {value}
-        
+        
     ))}
     {(props.experimental || []).map((value, index) => (
@@ -50,6 +52,12 @@ import Legend from "./_legend.mdx";
         
     ))}
+    {(props.rejected || []).map((value, index) => (
+      
+        
+        
+      
+    ))}
     {(props.none || []).map((value, index) => (
       

   
     

           
         ✅ Full Support✅ Supported
       
✔️ Partial Support
       
{value}
Not supported on native

         
diff --git a/content/v5/tailwind/borders/border-color.mdx b/content/v5/tailwind/borders/border-color.mdx
index 3ec971a..b95dfc8 100644
--- a/content/v5/tailwind/borders/border-color.mdx
+++ b/content/v5/tailwind/borders/border-color.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/borders/border-style.mdx b/content/v5/tailwind/borders/border-style.mdx
index 2cac7f4..9f4d376 100644
--- a/content/v5/tailwind/borders/border-style.mdx
+++ b/content/v5/tailwind/borders/border-style.mdx
@@ -11,9 +11,14 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+Use `border-0` to remove a native border by setting its width. The CSS `border-none` style is rejected.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/borders/outline-style.mdx b/content/v5/tailwind/borders/outline-style.mdx
index b644613..8a1f1fb 100644
--- a/content/v5/tailwind/borders/outline-style.mdx
+++ b/content/v5/tailwind/borders/outline-style.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/flexbox/flex-basis.mdx b/content/v5/tailwind/flexbox/flex-basis.mdx
index 68b0de8..5e5fe6f 100644
--- a/content/v5/tailwind/flexbox/flex-basis.mdx
+++ b/content/v5/tailwind/flexbox/flex-basis.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/flexbox/order.mdx b/content/v5/tailwind/flexbox/order.mdx
index da0f789..daca986 100644
--- a/content/v5/tailwind/flexbox/order.mdx
+++ b/content/v5/tailwind/flexbox/order.mdx
@@ -11,8 +11,12 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+Arrange native children in their intended order. CSS flex order does not reorder native views.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/interactivity/caret-color.mdx b/content/v5/tailwind/interactivity/caret-color.mdx
index e3dd1af..0f03994 100644
--- a/content/v5/tailwind/interactivity/caret-color.mdx
+++ b/content/v5/tailwind/interactivity/caret-color.mdx
@@ -11,8 +11,13 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+The RC caret mapping uses Android TextInput `cursorColor`. This does not establish iOS support for that prop.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/interactivity/user-select.mdx b/content/v5/tailwind/interactivity/user-select.mdx
index 43bb5c3..0b328b2 100644
--- a/content/v5/tailwind/interactivity/user-select.mdx
+++ b/content/v5/tailwind/interactivity/user-select.mdx
@@ -11,8 +11,12 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+The RC maps native `select-all` and `select-auto` to enabled Text selection, without promising CSS selection expansion semantics. In the pinned WebKit engine, `select-none` needs an explicit `WebkitUserSelect: "none"` style. The original Firefox select-all interaction remains unverified.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/layout/object-fit.mdx b/content/v5/tailwind/layout/object-fit.mdx
index 540093d..cb3ece6 100644
--- a/content/v5/tailwind/layout/object-fit.mdx
+++ b/content/v5/tailwind/layout/object-fit.mdx
@@ -11,6 +11,10 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+For React Native Web Image and Expo Image, use explicit `resizeMode` or `contentFit` props. A utility on the outer View does not establish the nested image fit. Native image adapters and HTML img elements have separate contracts.
+
 ## Compatibility
 
 
 
+## RC notes
+
+For Expo Image on web, use `contentPosition` explicitly and verify the rendered image. An outer View class does not establish the nested image position.
+
 ## Compatibility
 
 
 
+## RC notes
+
+Use ScrollView or other React Native scrolling components for scrolling. Whole view `overflow-hidden` and `overflow-visible` are distinct from CSS scroll containers.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/layout/position.mdx b/content/v5/tailwind/layout/position.mdx
index 057c163..3d6772a 100644
--- a/content/v5/tailwind/layout/position.mdx
+++ b/content/v5/tailwind/layout/position.mdx
@@ -11,9 +11,14 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+Use native layout, overlay or sticky header APIs for fixed or sticky behavior; CSS viewport positioning is not interchangeable.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/layout/top-right-bottom-left.mdx b/content/v5/tailwind/layout/top-right-bottom-left.mdx
index 6df0f3c..4db8b7f 100644
--- a/content/v5/tailwind/layout/top-right-bottom-left.mdx
+++ b/content/v5/tailwind/layout/top-right-bottom-left.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/height.mdx b/content/v5/tailwind/sizing/height.mdx
index 76a0a91..1ec37ed 100644
--- a/content/v5/tailwind/sizing/height.mdx
+++ b/content/v5/tailwind/sizing/height.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/max-height.mdx b/content/v5/tailwind/sizing/max-height.mdx
index a6dad0d..2fc9610 100644
--- a/content/v5/tailwind/sizing/max-height.mdx
+++ b/content/v5/tailwind/sizing/max-height.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/max-width.mdx b/content/v5/tailwind/sizing/max-width.mdx
index 6429be4..b6857be 100644
--- a/content/v5/tailwind/sizing/max-width.mdx
+++ b/content/v5/tailwind/sizing/max-width.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/min-height.mdx b/content/v5/tailwind/sizing/min-height.mdx
index 088efdd..2b29d10 100644
--- a/content/v5/tailwind/sizing/min-height.mdx
+++ b/content/v5/tailwind/sizing/min-height.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/min-width.mdx b/content/v5/tailwind/sizing/min-width.mdx
index 5fb236f..e51984a 100644
--- a/content/v5/tailwind/sizing/min-width.mdx
+++ b/content/v5/tailwind/sizing/min-width.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/sizing/width.mdx b/content/v5/tailwind/sizing/width.mdx
index feee410..70adc49 100644
--- a/content/v5/tailwind/sizing/width.mdx
+++ b/content/v5/tailwind/sizing/width.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/transforms/transform-origin.mdx b/content/v5/tailwind/transforms/transform-origin.mdx
index d5c218b..4d10be8 100644
--- a/content/v5/tailwind/transforms/transform-origin.mdx
+++ b/content/v5/tailwind/transforms/transform-origin.mdx
@@ -11,8 +11,13 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC notes
+
+Use React Native’s `transformOrigin` style directly when needed; this RC compiler rejects the named CSS transform origin utilities.
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/transitions-animation/animation.mdx b/content/v5/tailwind/transitions-animation/animation.mdx
index 164eff8..148a8a6 100644
--- a/content/v5/tailwind/transitions-animation/animation.mdx
+++ b/content/v5/tailwind/transitions-animation/animation.mdx
@@ -11,6 +11,10 @@ import Usage from "../_usage.tsx";
 
 
 
+## RC limitation on Android
+
+On the tested Reanimated 4.5.1 target, cancelling a running rotation with `animate-none` or removing its animation styles can leave the final transform in place on Android. This is tracked in [Reanimated issue 10507](https://github.com/software-mansion/react-native-reanimated/issues/10507) and reproduces with direct Reanimated controls. Do not assume cancellation resets the transform; verify the affected interaction in your app. See the [RC compatibility guide](https://github.com/nativewind/nativewind/blob/main/docs/rc-compatibility.md).
+
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/typography/text-decoration-color.mdx b/content/v5/tailwind/typography/text-decoration-color.mdx
index 11b6393..2ffaa33 100644
--- a/content/v5/tailwind/typography/text-decoration-color.mdx
+++ b/content/v5/tailwind/typography/text-decoration-color.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/typography/text-decoration-style.mdx b/content/v5/tailwind/typography/text-decoration-style.mdx
index 81301bf..560ffcb 100644
--- a/content/v5/tailwind/typography/text-decoration-style.mdx
+++ b/content/v5/tailwind/typography/text-decoration-style.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/typography/text-decoration.mdx b/content/v5/tailwind/typography/text-decoration.mdx
index 666aa96..76f9312 100644
--- a/content/v5/tailwind/typography/text-decoration.mdx
+++ b/content/v5/tailwind/typography/text-decoration.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility
 
 
diff --git a/content/v5/tailwind/typography/vertical-align.mdx b/content/v5/tailwind/typography/vertical-align.mdx
index 66f7cb3..caca2c9 100644
--- a/content/v5/tailwind/typography/vertical-align.mdx
+++ b/content/v5/tailwind/typography/vertical-align.mdx
@@ -14,5 +14,6 @@ import Usage from "../_usage.tsx";
 ## Compatibility