mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00

Files

Mohamed Boudra 4d6a154f6e Fix Unistyles theme splits

2026-04-18 15:06:42 +07:00

9.9 KiB

Raw Permalink Blame History

Unistyles Gotchas

This app uses react-native-unistyles v3 for theme-aware styles. Unistyles is fast because most style updates do not go through React renders: the Babel plugin rewrites React Native component imports, attaches style metadata, and lets the native ShadowRegistry update tracked views when theme or runtime dependencies change.

That model is powerful, but it has sharp edges. Use this note when adding theme-dependent styles.

How Updates Propagate

For standard React Native components, the Unistyles Babel plugin rewrites imports such as View, Text, Pressable, and ScrollView to Unistyles-aware component factories. On native, those factories borrow the component ref and register the style prop with the ShadowRegistry. The upstream "Why my view doesn't update?" guide describes this as the ShadowTree update path that avoids unnecessary React re-renders.

The important detail: the automatic native path tracks props.style. It does not generally track every prop that happens to carry style-like values.

useUnistyles() is different. It gives React access to the current theme/runtime and can make a component re-render when those values change. Use it for values that must be rendered through React props, such as icon colors or small escape hatches. Do not expect direct reads from UnistylesRuntime to re-render a component; issue #817 is a useful reminder of that invariant.

Main Gotcha: `contentContainerStyle`

ScrollView.contentContainerStyle is the canonical trap. It looks like a style prop, but it is not the same prop that Unistyles' remapped native component registers by default. The upstream tutorial calls this out directly in its ScrollView Background Issue section.

Avoid this pattern when the style depends on the theme:

<ScrollView contentContainerStyle={styles.container} />

const styles = StyleSheet.create((theme) => ({
  container: {
    flexGrow: 1,
    backgroundColor: theme.colors.surface0,
  },
}));

On first mount this can paint with the current adaptive or initial theme. If app settings later load a persisted theme and call UnistylesRuntime.setTheme, the JS-side style proxy may report the new theme while the native content container keeps the old background. That is how the welcome screen ended up with a light background and dark foreground/buttons.

This applies broadly to non-style props that carry theme-dependent values, such as component props named color, trackColor, tintColor, and library-specific style props. The 3rd-party view decision algorithm recommends explicit handling for these cases, and issue #1030 shows a related native-prop update edge case around Image.tintColor. Treat these values as React props unless wrapped with withUnistyles.

Fix Patterns

Preferred pattern: put themed backgrounds on a normal wrapper view, and keep contentContainerStyle theme-free.

<View style={styles.container}>
  <ScrollView contentContainerStyle={styles.contentContainer}>
    {children}
  </ScrollView>
</View>

const styles = StyleSheet.create((theme) => ({
  container: {
    flex: 1,
    backgroundColor: theme.colors.surface0,
  },
  contentContainer: {
    flexGrow: 1,
    padding: theme.spacing[4],
  },
}));

This is the pattern used by the settings screen: the screen background lives on a normal View style={styles.container}, while the scroll content container only carries layout.

When the content container itself needs themed behavior, wrap the component with withUnistyles:

import { ScrollView } from "react-native";
import { StyleSheet, withUnistyles } from "react-native-unistyles";

const ThemedScrollView = withUnistyles(ScrollView);

<ThemedScrollView
  style={styles.scrollView}
  contentContainerStyle={styles.contentContainer}
/>

withUnistyles extracts dependency metadata from both style and contentContainerStyle, subscribes to the relevant theme/runtime changes, and re-renders only that wrapped component when needed. Its auto-mapping behavior for style and contentContainerStyle is the reason it fixes themed ScrollView content containers. Reach for it when wrapper-view layout would be awkward or when a third-party component needs theme-aware non-style props mapped through Unistyles.

The smallest escape hatch is to use useUnistyles() and pass an inline value through React:

const { theme } = useUnistyles();

<ScrollView
  contentContainerStyle={[
    styles.contentContainer,
    { backgroundColor: theme.colors.surface0 },
  ]}
/>

Use this sparingly. It works because React re-renders the prop, but it gives up the main Unistyles native-update path for that value.

Hidden Sheet Content

@gorhom/bottom-sheet can keep BottomSheetModal content mounted while the sheet is hidden. That matters during Paseo's startup theme transition: a header node can be created under the initial adaptive theme, stay hidden, then appear later with stale native style values even though surrounding content has re-rendered correctly.

We saw this in AdaptiveModalSheet: the body text and buttons were dark-theme-correct, but the shared sheet title opened with the initial light-theme text color on a dark sheet background. For tiny values in a reusable sheet header, prefer the inline escape hatch:

const { theme } = useUnistyles();

<Text style={[styles.title, { color: theme.colors.foreground }]}>
  {title}
</Text>

Keep layout and typography in StyleSheet.create; move only the stale theme-dependent value through React. If a larger subtree shows the same behavior, consider remounting the sheet on theme changes or moving the themed paint onto a wrapper that is mounted with the visible content.

Adaptive Themes And Persisted Settings

Unistyles initialTheme and adaptiveThemes are mutually exclusive. initialTheme can be a string or a synchronous function, but it cannot wait on async storage.

Paseo currently stores app settings in AsyncStorage and loads them through react-query. That means the app can mount under adaptive/system theme first, then switch after settings load:

Unistyles config starts with adaptiveThemes: true.
The device may report system light.
Settings load a persisted non-auto preference, such as dark.
The app calls setAdaptiveThemes(false) and setTheme("dark").

That brief transition is expected with the current storage model. It makes tracking-compatible styles important: anything mounted during the initial adaptive theme must update correctly after the persisted preference applies. Issue #550 was a separate ScrollView sticky-header bug, but it is still useful context for why ScrollView theme updates deserve extra suspicion.

If we ever need to avoid the transition entirely, store at least the theme preference in synchronous storage and configure Unistyles with initialTheme.

Debugging

To inspect what the Babel plugin sees, temporarily enable debug: true in packages/app/babel.config.js:

[
  "react-native-unistyles/plugin",
  {
    root: "src",
    debug: true,
  },
],

Then rebuild the bundle and look for lines such as:

src/components/welcome-screen.tsx: styles.container: [Theme]

This only confirms that the stylesheet dependency was detected. The upstream debugging guide makes the same distinction: dependency detection is only one failure mode. It does not prove the style prop is registered on the native view you care about.

For paint-layer bugs, use high-contrast probes:

Paint each candidate layer a distinct color, such as root wrapper cyan, ScrollView.style yellow, and contentContainerStyle magenta.
Cold-restart the app, not just Fast Refresh.
Screenshot the simulator and sample pixels to see which color fills the area.
Remove the probes before committing.

The welcome-screen investigation used this approach to prove the white layer was the ScrollView content container. Deep-dive evidence is in welcome-theme-split-research.md.

9.9 KiB Raw Permalink Blame History