Theming

Customize the look and feel of Crossbuild UI components to match your application's brand.

How Theming Works

Crossbuild UI uses a flexible theming system that allows you to override default styles, define custom color palettes, and adjust layout properties.

Projects Created with `cbui-cli`

If you initialized your project using cbui-cli init, a theme configuration file named myCustomTheme.ts is automatically created in your project's styles folder (or a similar conventional location). You can directly edit this file to apply your custom theme.

Manual Configuration / Existing Projects

For existing projects or manual setups:

Ensure you have the @crossbuildui/core package (or your main UI package) installed. You can install it using
```
$ npm install @crossbuildui/core
```
Create a new file, for example, myCustomTheme.ts, typically in a src/styles or styles directory.
In this file, import AppConfig and defaultAppConfig from @crossbuildui/core. Define your custom theme by providing a partial AppConfig object.

Here’s an example of how you can override parts of the default theme:

myCustomTheme.ts

import { AppConfig, defaultAppConfig } from '@crossbuildui/core';

export const myCustomTheme: Partial<AppConfig> = {
  themes: {
    light: {
      colors: {
        primary: {
          // ...defaultAppConfig.themes.light.colors.primary, // Optional: spread default if you only change some shades
          '50': '#e6f7ff', // Lighter shade
          '100': '#bae7ff',
          '200': '#91d5ff',
          '300': '#69c0ff',
          '400': '#40a9ff',
          '500': '#FF5733', // Your custom primary color
          '600': '#d9482e',
          '700': '#b33c28',
          '800': '#8c2f21',
          '900': '#66221a',
          'foreground': '#FFFFFF', // Text color on primary background
          'DEFAULT': '#FF5733',   // Default primary color
        },
        // You can override other colors like secondary, success, etc.
      },
    },
    dark: {
      // Similar overrides for dark theme
      colors: {
        primary: {
          '500': '#FF8C66', // A corresponding dark theme primary
          'DEFAULT': '#FF8C66',
        }
      }
    }
  },
  layout: {
    borderRadius: {
      sm: 6, // Custom small border radius
      md: 10, // Custom medium border radius
      // ... other layout properties
    }
  }
};
  

You can override as little or as much as you need. The structure must follow the AppConfig type. If you provide completely custom values, ensure they adhere to the expected format for colors (typically a scale from 50 to 900, plus DEFAULT and foreground) and layout properties.

After defining your theme, you'll need to provide it to the Crossbuild UI Provider at the root of your application. Refer to the Provider documentation for specific integration steps.

Usage

To apply your theme (either default or custom) throughout your application, you need to wrap your root component with the ThemeProvider.

1. Wrap Your Application with ThemeProvider

In your main App.tsx (or equivalent entry file):

App.tsx

import React from 'react';
import { ThemeProvider, View, Text, defaultAppConfig } from '@crossbuildui/core';
// import { myCustomTheme } from './styles/myCustomTheme'; // Assuming your theme is here

const App = () => {
  // To use a custom theme, merge it with defaultAppConfig or provide it fully:
  // const themeToUse = myCustomTheme; // If myCustomTheme is a complete AppConfig
  // Or, for partial overrides:
  // const themeToUse = { ...defaultAppConfig, ...myCustomTheme };

  return (
    // <ThemeProvider theme={themeToUse}> {/* With custom theme */}
    <ThemeProvider> {/* With default theme */}
      <MainScreen />
    </ThemeProvider>
  );
};

const MainScreen = () => {
  // Your app's main screen content
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Hello from CrossBuild UI!</Text>
    </View>
  );
};

export default App;

2. Using Themed Components and `useTheme` Hook

Once the ThemeProvider is set up, all Crossbuild UI components within its scope will automatically adapt to the active theme. You can also access theme properties and functions directly in your components using the useTheme hook:

MyComponent.tsx

import React from 'react';
import { View, Text, Button, useTheme } from '@crossbuildui/core';

const MyComponent = () => {
  const { colors, mode, layout, toggleTheme, isDark } = useTheme();

  return (
    <View style={{ backgroundColor: colors.background, padding: layout.borderRadius.md }}>
      <Text style={{ color: colors.primary.DEFAULT }}>Current mode: {mode}</Text>
      <Text style={{ color: colors.foreground }}>Is Dark Mode: {isDark ? 'Yes' : 'No'}</Text>
      <Button onPress={toggleTheme} title="Toggle Theme" />
    </View>
  );
};

export default MyComponent;

The useTheme hook provides access to the current theme's colors, active mode (e.g., 'light' or 'dark'), layout configurations, a boolean isDark flag, and a toggleTheme function to switch between light and dark modes.

Installation Footer Navbar