react-native-ui-app-components

react-native-ui-app-components is a flexible, customizable library designed to simplify building app UIs in React Native. With pre-built components, utility-based design and a robust theming system, it allows developers to build responsive and visually consistent layouts quickly and efficiently. The theming system supports dynamic theme switching and customization, making it easy to adapt to different design requirements.

Installation

npm install react-native-ui-app-components

Components Overview

• AppThemeProvider: Provides a theme context to manage and switch between light and dark modes.
• AppView: A flexible container component that extends the View from React Native with powerful and theme-reactive props, enabling quick and custom layout building.
• AppText: A versatile text component that extends the Text from React Native with theme-reactive props, allowing for quick and dynamic text styling.
• AppSafeAreaLayout: Ensures that content is displayed within the safe area boundaries of a device. Uses SafeAreaProvider and SafeAreaView with little but useful additions.

Detailed Component Documentation

AppThemeProvider

The AppThemeProvider is a context provider component designed to manage and provide theming capabilities throughout your React Native application. It allows you to define and customize theme properties such as colors, font sizes, and other styling attributes, and makes them accessible to all components within your application.

By wrapping your application with the AppThemeProvider, you can easily switch between light and dark themes, or let the theme automatically adapt to the device's color scheme. Additionally, you can override specific theme properties to tailor the appearance of your app to your needs.

Key Features:

• Theme Management: Provides a centralized way to manage and apply themes across your application.
• Customizable: Allows you to override default theme properties with custom values.
• Responsive to Device Settings: Automatically adapts to the device's color scheme (light or dark mode).
• Easy Integration: Simple to integrate and use within your existing React Native application.

Usage Examples

Example 1: Using All Default Values

// these are all the default values
const defaultInitialTheme: InitialTheme = {
  backgroundColorDark: '#030303',
  backgroundColorLight: '#ffffff',

  backgroundColorModalDark: '#090909',
  backgroundColorModalLight: '#fafafa',

  backgroundColorPrimaryDark: '#0D0D0D',
  backgroundColorPrimaryLight: '#f2f2f2',

  fontSizeSmall: 12,
  fontSizeMid: 14,
  fontSizeHeadingSmall: 16,
  fontSizeHeadingMid: 20,

  textColorPrimaryDark: 'black',
  textColorPrimaryLight: '#f2f2f2',

  textColorSecondaryDark: 'rgba(0, 0, 0, 0.5)',
  textColorSecondaryLight: 'rgba(255, 255, 255, 0.7)',

  borderColorDark: '#0000002a',
  borderColorLight: '#ffffff2a',
};

// inside _layout.tsx
import { AppThemeProvider } from "react-native-ui-app-components";

export default function Layout() {
  return (
    <AppThemeProvider>
      {/* all your children (Stacks, Tabs, whatever) */}
    </AppThemeProvider>
  );
}

Example 2: Overriding Specific (or All) Theme Properties

You can customize only the parts of the theme that you need to change, while relying on the default values for everything else. You can import InitialTheme type to help you build the object.

// inside _layout.tsx
import { InitialTheme, AppThemeProvider } from "react-native-ui-app-components";

export default function Layout() {

  // declare what to override, everything else will use default value
  const initialTheme: InitialTheme = {
    fontSizeHeadingMid: 24,
  };

  return (
    <AppThemeProvider
      initialTheme={initialTheme}>
      {/* all your children (Stacks, Tabs, whatever) */}
    </AppThemeProvider>
  );
}

Accessing the theme:

To access what the context gives you, use the useAppTheme hook:

const { theme, initialTheme } = useAppTheme();

The initialTheme object is the object passed to the provider combined with defaultInitialTheme. It provides all the initial properties used to create the responsive theme, replacing the default values with those overridden (if overridden) by the user.

The object theme is the "reactive" one. When color scheme changes, properties get updated:

export type AppTheme = {
  currentColorScheme: ColorSchemeName; // "light" | "dark"

  backgroundColor: string;
  backgroundColorModal: string;
  backgroundColorPrimary: string;

  textColorPrimary: string;
  textColorSecondary: string;

  borderColor: string;
};

To build a settings page properly, you should use a set of three radio buttons for selecting the theme:

• Auto (will detect the theme of the phone)
• Light
• Dark

  // what to use
  const {
    selectedColorScheme, // "light" | "dark" | "auto"
    handleAutoColorScheme,
    handleLightColorScheme,
    handleDarkColorScheme
  } = useAppTheme();

For the button selected state, you have to use selectedColorScheme because in addition to light and dark it also provides auto, which is needed to highlight the "Auto" button if selected.

The three functions handleAutoColorScheme, handleLightColorScheme and handleDarkColorScheme set the theme to the selected one and update the user's preferences in Async Storage.

Instead, theme.currentColorScheme provides “light” or “dark,” which is the actual current theme. So, wherever you need to know the current theme, use it.

AppView, AppText, AppSafeAreaLayout

Coming very soon.

License

MIT