UI and Theming

How we manage the UI and theming of the application.

Why Tailwind CSS ?

For the past few years, we have tried multiple approaches to style our React Native apps: Stylesheet API, styled-components, restyle, and more.

Right now, we are confident that using Tailwind CSS with React Native is the right solution, especially after trying Uniwind.

If you are familiar with Tailwind CSS on the web you will find it very easy to use and you can even copy past your styling from a web application and should work without issues with react native too with some minor adjustments of course.

Last but not least, Tailwind CSS was a natural choice for us, considering that most of our team members come from a web background and have had the opportunity to work with Tailwind CSS before.

Tip

If you are not familiar with Tailwind CSS, we recommend you read the Tailwind CSS documentation first.

We would also recommend playing with the Tailwind CSS playground to get a better understanding of how it works as well as practicing by building a simple web app with it before jumping into react native.

About Uniwind

Uniwind is a library that allows you to use Tailwind CSS with React Native. Uniwind achieves this by pre-compiling Tailwind CSS classes into React Native stylesheets with a minimal runtime to selectively apply the styles.

Uniwind provides an efficient development experience with a utility-first approach that simplifies the styling process by using classes and applying styles directly within JSX elements.

For more details about Uniwind you can check their documentation.

Here is an example of how your component should look like:

src/features/feed/components/post-card.tsx

import type { Post } from '../api';

import { Link } from 'expo-router';
import * as React from 'react';

import { Image, Pressable, Text, View } from '@/components/ui';

const images = [
  'https://images.unsplash.com/photo-1489749798305-4fea3ae63d43?auto=format&fit=crop&w=800&q=80',
  'https://images.unsplash.com/photo-1564507004663-b6dfb3c824d5?auto=format&fit=crop&w=800&q=80',
  'https://images.unsplash.com/photo-1515386474292-47555758ef2e?auto=format&fit=crop&w=800&q=80',
  'https://plus.unsplash.com/premium_photo-1666815503002-5f07a44ac8fb?auto=format&fit=crop&w=800&q=80',
  'https://images.unsplash.com/photo-1587974928442-77dc3e0dba72?auto=format&fit=crop&w=800&q=80',
];

type Props = Post;

export function PostCard({ title, body, id }: Props) {
  return (
    <Link href={`/feed/${id}`} asChild>
      <Pressable>
        <View className="m-2 overflow-hidden rounded-xl border border-neutral-300 bg-white dark:bg-neutral-900">
          <Image
            className="h-56 w-full overflow-hidden rounded-t-xl"
            contentFit="cover"
            source={{
              // eslint-disable-next-line react-hooks/purity
              uri: images[Math.floor(Math.random() * images.length)],
            }}
          />

          <View className="p-2">
            <Text className="py-3 text-2xl">{title}</Text>
            <Text numberOfLines={3} className="leading-snug text-gray-600">
              {body}
            </Text>
          </View>
        </View>
      </Pressable>
    </Link>
  );
}

Configuration

Uniwind is the same as Tailwind CSS, it comes with a default theme and colors that you can override by creating your own theme and colors.

You need to understand that Uniwind is a library that is built on top of Tailwind CSS. Feel free to add any Tailwind CSS config that you want to use in your application such as updating colors, spacing, typography, etc.

We have created a ui/theme folder where you can find our custom colors that have been imported into tailwind.config.js and used as a theme for our demo application. You can add your own color palette and use them in your components with Tailwind class names.

You can read more about how to configure your project with Tailwind CSS.

Dark Mode

Why dark mode?

Dark mode has gained significant traction in recent years and has become an expected feature to have. By applying dark mode, it makes it easier on the eyes in low-light environments and reduces eye strain, which means more time spent on your app.

This template comes with dark mode support out of the box, and it’s very easy to customize the color scheme of your app. Thanks to tailwindcss

Implementation

Since we’re using uniwind (which uses Tailwind CSS under the hood) and expo-router we let them handle the application of theme, and we just take care of the colors we want. We set the colors in ui/theme/colors.js and we use them in our hook useThemeConfig.tsx to get the theme object that we pass to ThemeProvider directly. For more information check out expo-router

src/components/ui/use-theme-config.tsx

import type { Theme } from '@react-navigation/native';
import {
  DarkTheme as _DarkTheme,
  DefaultTheme,
} from '@react-navigation/native';
import { useUniwind } from 'uniwind';

import colors from '@/components/ui/colors';

const DarkTheme: Theme = {
  ..._DarkTheme,
  colors: {
    ..._DarkTheme.colors,
    primary: colors.primary[200],
    background: colors.charcoal[950],
    text: colors.charcoal[100],
    border: colors.charcoal[500],
    card: colors.charcoal[850],
  },
};

const LightTheme: Theme = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    primary: colors.primary[400],
    background: colors.white,
  },
};

export function useThemeConfig() {
  const { theme } = useUniwind();

  if (theme === 'dark')
    return DarkTheme;

  return LightTheme;
}

src/app/_layout.tsx

import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';

import { ThemeProvider } from '@react-navigation/native';
import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';
import * as React from 'react';
import { StyleSheet } from 'react-native';
import FlashMessage from 'react-native-flash-message';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { KeyboardProvider } from 'react-native-keyboard-controller';
import { useThemeConfig } from '@/components/ui/use-theme-config';
import { hydrateAuth } from '@/features/auth/use-auth-store';

import { APIProvider } from '@/lib/api';
import { loadSelectedTheme } from '@/lib/hooks/use-selected-theme';
// Import  global CSS file
import '../global.css';

export { ErrorBoundary } from 'expo-router';

// eslint-disable-next-line react-refresh/only-export-components
export const unstable_settings = {
  initialRouteName: '(app)',
};

hydrateAuth();
loadSelectedTheme();
// Prevent the splash screen from auto-hiding before asset loading is complete.
SplashScreen.preventAutoHideAsync();
// Set the animation options. This is optional.
SplashScreen.setOptions({
  duration: 500,
  fade: true,
});

export default function RootLayout() {
  return (
    <Providers>
      <Stack>
        <Stack.Screen name="(app)" options={{ headerShown: false }} />
        <Stack.Screen name="onboarding" options={{ headerShown: false }} />
        <Stack.Screen name="login" options={{ headerShown: false }} />
      </Stack>
    </Providers>
  );
}

function Providers({ children }: { children: React.ReactNode }) {
  const theme = useThemeConfig();
  return (
    <GestureHandlerRootView
      style={styles.container}
      // eslint-disable-next-line better-tailwindcss/no-unknown-classes
      className={theme.dark ? `dark` : undefined}
    >
      <KeyboardProvider>
        <ThemeProvider value={theme}>
          <APIProvider>
            <BottomSheetModalProvider>
              {children}
              <FlashMessage position="top" />
            </BottomSheetModalProvider>
          </APIProvider>
        </ThemeProvider>
      </KeyboardProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

How do we handle theme changes?

We use the loadSelectedTheme function to load the theme from the storage if there’s a theme saved in the storage, otherwise, we let uniwind use the default theme (system). To set the selected theme, we use the useSelectedTheme hook, which sets the theme in the storage and updates the color scheme of the app.

src/lib/hooks/use-selected-theme.tsx

import * as React from 'react';
import { useMMKVString } from 'react-native-mmkv';
import { Uniwind, useUniwind } from 'uniwind';

import { storage } from '../storage';

const SELECTED_THEME = 'SELECTED_THEME';
export type ColorSchemeType = 'light' | 'dark' | 'system';
/**
 * this hooks should only be used while selecting the theme
 * This hooks will return the selected theme which is stored in MMKV
 * selectedTheme should be one of the following values 'light', 'dark' or 'system'
 * don't use this hooks if you want to use it to style your component based on the theme use useUniwind from uniwind instead
 *
 */
export function useSelectedTheme() {
  const { theme: _theme } = useUniwind();
  const [theme, _setTheme] = useMMKVString(SELECTED_THEME, storage);

  const setSelectedTheme = React.useCallback(
    (t: ColorSchemeType) => {
      Uniwind.setTheme(t);
      _setTheme(t);
    },
    [_setTheme],
  );

  const selectedTheme = (theme ?? 'system') as ColorSchemeType;
  return { selectedTheme, setSelectedTheme } as const;
}
// to be used in the root file to load the selected theme from MMKV
export function loadSelectedTheme() {
  const theme = storage.getString(SELECTED_THEME);
  if (theme !== undefined) {
    console.log('theme', theme);
    Uniwind.setTheme(theme as ColorSchemeType);
  }
}

Add dark mode for each component

To add the values for the light mode, you can simply write them directly in your component class. For the dark mode, you can use the dark: variant.

<View className="... border-neutral-200 dark:border-yellow-700">....</View>

If you want to use the style prop, you can use the useColorScheme hook to get the current color scheme and use it to apply the desired style. However, in most cases, you won’t need it as the dark: variant will do the job.

import { useColorScheme } from 'uniwind';

const colorScheme = useColorScheme();
const style =
  colorScheme === 'dark'
    ? { backgroundColor: 'black' }
    : { backgroundColor: 'white' };

For more details about dark mode, you can check tailwind and uniwind