@carbon/react-native
v8.1.3
Published
Carbon for React Native Library
Downloads
2,756
Readme
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
- Go into the
ios
directory and runpod install
(be sure to use the system Ruby on Mac if you are using rvm or similar tool) - 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 ], };
- Run
npx react-native-asset
to link the fonts (install this package if not already). - 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
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.