Carbon for React Native

The React Native implementation of the Carbon Design System.

Component and shared patterns for React Native apps using Carbon. Styles are based on the Carbon Native Mobile designs. Color (g10 for light theme and g100 for dark theme) and typography tokens are based on Carbon v11.

Documentation

Documentation can be found here. This documentation is auto generated by the TypeScript files. To use the documentations you can find each component on the left side as a Class. Each component has a link to the example app code and the Props (Component<ItemProps>) which can be jumped to by clicking the ItemProps. Props will indicate all props this component supports with documentation. Links will jump to related to type declarations.

Getting started

To install @carbon/react-native in your project, you will need to run the following command using npm:

npm install -S @carbon/react-native

If you prefer Yarn, use the following command instead:

yarn add @carbon/react-native

1. Go into the ios directory and run pod install (be sure to use the system Ruby on Mac if you are using rvm or similar tool)
2. Create or edit react-native.config.js file to be:

   module.exports = {
     project: {
       ios: {},
       android: {},
     },
     assets: [
       './node_modules/@carbon/react-native/src/assets/fonts/', // This needs to be added if file already exists
     ],
   };

3. Run npx react-native-asset to link the fonts (install this package if not already).
4. Install the following peer dependencies (install as dependencies. See dependecies here for tested versions):
   • @carbon/themes
   • @carbon/icons
   • @carbon/icon-helpers
   • react-native-svg
   • react-native-webview
   • react-native-safe-area-context

Important: This library does not support EXPO by default. This library is designed and developed without EXPO. If you are using EXPO you will need to do additioanl items to alter the build and setup to make it work. Please do not open tickets about issues with EXPO, the app is only tested to run with React Native.

Recommended Settings

For best experience with navigation we recommend for Android setting android:windowSoftInputMode="adjustPan" in your AndroidManifest file. This will prevent the bottom navigation from pushing up. Other known mechanisms exist and you should consider keyboard overlay for developing input areas.

Usage

Components

import { Button } from '@carbon/react-native';

<Button kind="primary" text="My Button" onPress={() => {}} />;

Colors

You can use getColor to retrieve a color token using the system theme for Carbon colors. You can pass a second param to force a theme (light/dark).

import { getColor } from '@carbon/react-native';

const styles = StyleSheet.create({
  example: {
    padding: 16,
    color: getColor('textPrimary'),
    backgroundColor: getColor('background'),
  },
});

Color scheme will follow the OS. You can request specific colors at any point via second param on get Color. If you wish to use a theme for your app you will need to set the theme globally. This means that any color you use in your own styling will need to be done via a getter (and have this component reload its state). For changing your own colors on the fly you need to ensure getters are used for those styles using color. You can use the forceTheme function to change the theme and trigger a state update to change the color.

Icons

You can use icons from @carbon/icons to pass to components. We do not bundle all icons in this library to reduce size. You can import specific icons from that library directly as needed. An example of how to pass icons to the React Native components is below.

import AddIcon from '@carbon/icons/es/add/20';

// Using an icon with a component that supports Carbon Icons.
<Button icon={AddIcon} />

// Using an icon directly in your own component. You can use our helper.  See `createIcon` params for options.
<View>{createIcon(icon, 20, 20)}</View>

Overriding Themes

You can override the default Carbon theme (Carbon Colors and IBM Plex) by using the built in theme override calls. These should be done first in your app during a loading state or initial load. If done after app load any component already rendered needs to redraw state.

Overriding colors

Colors can be overridden by using overrideLightTheme or overrideDarkTheme. If you wish to use only one theme for your app you can simply forceTheme as well to lock the app to a single theme. Colors are written in camelCase and follow the tokens found at Carbon Design Systems.

Overriding fonts

Fonts can be overridden on individual components by overriding the styles (fontFamily, fontWeight). However, you can also override them globally. By calling overrideFonts which takes in a family and weight for each of the internal font groups components use. If you use a font be sure to use one that is supported on the OS you are running. Android and iOS have different supported fonts. You can also use custom fonts as long as you bundle them as part of your app. It is a similar process to how we add Plex above in the "Getting started" section.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.