React Native Theming 2025!

Good day, everyone! Today we'll talk about theme-csx, a new react native theming library that was created to alleviate the pain that developers may experience when attempting to add dark mode support to mobile apps.

Github Link: https://github.com/KJ-GM/theme-csx

Without further ado, let's get started:

✨ Features

• ⚡️ Light / Dark / System theme support
• 🍏 Dynamic iOS color adaptation
• 💾 MMKV-based persistent theme storage
• 🧠 Memoized themed styles with createThemedStyles
• 🔐 Type-safe access to theme tokens (with autocomplete)
• 🚀 Scalable for monorepos and multi-app setups
• 🧩 Extendable (spacing, typography, shadows, etc.)

✅ iOS: theme changes apply instantly

🔁 Android: theme changes apply on app restart

📦 Installation

# npm
npm install theme-csx

# yarn
yarn add theme-csx

# pnpm
pnpm add theme-csx

🚀 Quick Start

1. Define your own theme

Create your own theme object.

It must include a colors.light and colors.dark object. Everything else (e.g. spacing, typography, radius) is optional and customizable.

// theme/theme.ts

export const theme = {
  colors: {
    light: {
      background: '#ffffff',
      text: '#111111',
    },
    dark: {
      background: '#000000',
      text: '#ffffff',
    },
  },
  spacing: {
    sm: 8,
    md: 16,
    lg: 24,
  },
  // Add any other tokens you want (typography, radius, etc.)
};

2. Create your theme system

Use createAppTheme() to initialize your theming system.

This should be called only once in your app to avoid unexpected behavior.

You can enable persistent theme mode storage (optional) by setting { storage: true }.

⚠️ Requires react-native-mmkv if storage is enabled.

// theme/index.ts

import { createAppTheme } from 'theme-csx';
import { theme } from './theme';

export const {
  AppThemeProvider,
  useTheme,
  useThemeMode,
  useSetThemeMode,
  useResetThemeMode,
  useToggleThemeMode,
  createThemedStyles,
} = createAppTheme(theme, {
  storage: true, // Optional: disables persistence if omitted or set to false
});

3. Wrap your app

Wrap your app with AppThemeProvider and you are all set 🚀.

// App.tsx
import { AppThemeProvider } from '@theme';

export default function App() {
  return (
    <AppThemeProvider>
      {/* your app code */}
    </AppThemeProvider>
  );
}

🎨 Usage

- Access current theme

import { useTheme } from '@theme';

const MyComponent = () => {
  const theme = useTheme();
  return <View style={{ backgroundColor: theme.colors.background }} />;
};

- Themed styles (Efficient)

import { createThemedStyles } from '@theme';

const useStyles = createThemedStyles((theme) => ({
  container: {
    flex: 1,
    backgroundColor: theme.colors.background,
    padding: theme.spacing.md,
  },
  text: {
    color: theme.colors.text,
  },
}));

const MyComponent = () => {
  const styles = useStyles();
  return <Text style={styles.text}>Hello</Text>;
};

- Toggle theme mode

import { useToggleThemeMode  } from '@theme';

const ToggleButton = () => {
  const toggleTheme = useToggleThemeMode();

  return <Button title="Toggle Theme" onPress={toggleTheme} />;
};

🔧 Other Utilities

Once you initialize your theme system with createAppTheme(), you get access to the following utilities:

Utility	Description
useTheme()	Access the current theme (colors, colorMode, and custom tokens).
useThemeMode()	Get the current theme mode (light, dark, or system).
useSetThemeMode()	Change the theme mode programmatically.
useResetThemeMode()	Reset to system theme mode (and clear stored preference if storage: true).
useToggleThemeMode()	Toggle strictly between light and dark modes.
useCycleThemeMode()	Cycle through modes: light → dark → system → light.
createThemedStyles()	Create memoized themed styles using your theme object.

All of these must be used within your AppThemeProvider tree.

🧩 Best Practices

✅ Always wrap your app in AppThemeProvider

✅ Use useTheme() for direct access to the theme

✅ Use createThemedStyles() to keep styles performant and memoized

✅ Use storage: true only if react-native-mmkv is installed

🚫 Do not call createAppTheme() more than once per app