Proposal: ScopedThemes support

[Brentlok]

This topic has been brought up in multiple channels, so I am creating this discussion to summarize the requirement and our proposed solution.

Context

There is a strong demand in the community for a component that forces a specific theme for a specific tree of components. This concept already exists in Unistyles 3.0 (see: Unistyles Scoped Theme).

Proposed API

We discussed this internally and decided to align with a similar syntax. We propose exporting a new component from uniwind called <ScopedTheme />.

It will accept a single prop, theme, which will be:

1. Automatically typed based on your theme definitions.
2. Cascading, forcing all children within that tree to resolve styles against the specified theme.

import { ScopedTheme } from 'uniwind'

export const App = () => {
    return (
        <View>
            <Header />
            {/* This tree of components will always use the "premium" theme */}
            <ScopedTheme theme="premium"> 
                <PageContent />
            </ScopedTheme>
        </View>
    )
}

Technical Considerations & Challenges

We are currently investigating the following areas to ensure a robust implementation:

• Performance: We need to decide whether to use React's Context API or a different mechanism. Our priority is ensuring this does not negatively impact render performance.
• Caching: The uniwind cache logic will need to be updated to be "scope-aware" so that styles generated for the scoped theme do not conflict with the global theme.
• Web Support: We need to determine how this translates to the web (e.g., scoping CSS variables vs. class name generation).
• Suspense Support: We previously encountered challenges with Suspense boundaries in the unistyles implementation; we aim to solve these for uniwind.
• API Compatibility: Ensuring seamless integration with existing hooks and HOCs, such as useResolveClassName, withUniwind, and useCSSVariable.

Roadmap

We aim to land this feature in Q1 2026. It will be available for both the free and Pro versions

Feedback request

We would love to hear your thoughts on the proposed API.

[Tehnix]

The API looks exactly like what I'd wish for 🙌

I'm currently doing some shenanigans where I track a "temporary" theme change so that I can reset it later to the users preferred/chosen theme.

I'm using Expo, so what I do currently is to call a setTemporaryTheme function in the _layout.tsx of the routes where I want the specific theme to take effect (in my case, during Onboarding), and then reset it at the end of the steps in the Route.

It's not perfect, and has some of the issues described in #300, but it's something I can live with knowing that there is a proper solution on the way with this proposal 😁 I can really only do it because it's for the entire page that I want it, and my current solution wouldn't work if I only needed to change a part of the screen.

[saseungmin]

Thanks for putting this together! The proposed API looks clean and straightforward.
We're currently using NativeWind v4 in a multi-brand entertainment app and planning to upgrade to Reanimated v4 and Tailwind v4. We tried upgrading to NativeWind v5 but ran into too many issues, so we're now considering migrating to Uniwind since it supports Tailwind CSS syntax as-is.

That said, scoped theme is a must-have for our architecture, so it's currently the main blocker for migration. Specifically, we need multiple nesting — app-level default theme → screen-level brand theme — so child components including modals resolve styles against the closest .

<ScopedTheme theme="default">
  <Screen>
    <ScopedTheme theme="brandA">
      <Content />
    </ScopedTheme>
    <ScopedTheme theme="brandB">
      <Modal />
    </ScopedTheme>
  </Screen>
</ScopedTheme>

If this lands within Q1 as planned, we'd be ready to move forward. We're also considering the Pro version.
Thank you for building and maintaining such an excellent library — Uniwind is truly outstanding. Looking forward to this feature!

[brunowilliang]

I was going to start a discussion about that lol, I need to do that in an app, any news about this feature?

[Brentlok]

I've started working on it, currently no ETA. But for sure it will land in Q1