kristerkari / react-native-css-modules

Style React Native components using CSS, PostCSS, Sass, Less or Stylus.

React Native CSS modules

Style React Native components using CSS, PostCSS, Sass, Less or Stylus.

Quick links: Features • Documentation • Example Apps • Development • FAQ

Features

• 🎉 You can share your CSS modules between React Native and React Web by using className property in React Native, and by using React Native for Web for the browser.
• 👌 Supports CSS, PostCSS, Sass, Less and Stylus.
• 🔥 CSS Hot loading (live reloading).
• 💻 Supports responsive CSS features: CSS Media Queries and CSS Viewport Units.
• ✨ Supports CSS variables.
• 🌐 Platform-specific extensions for CSS, e.g. styles.ios.css, styles.android.css, styles.native.css.
• 🎩 Support for styleName attribute that allows you to use CSS class names as strings, and allows hyphens in class names (like the className property in Web React).
• 📦 Suppports Typescript with React Native type definitions that add support for React Native CSS modules and CSS, Sass, LESS, PostCSS, or Stylus transformers that automatically create typings for your CSS files.
• 🔍 Keep your CSS error free using a custom stylelint config for React Native CSS modules

Examples

Using React Native CSS modules works almost the same way as using CSS modules with a Web React project, but there are some limitations. There is no support complex CSS selectors. Only simple CSS class selector (e.g. .myClass) is supported. React Native also only supports a subset of browser's CSS properties for styling.

For more info about the differences between using CSS modules in Web and React Native, have a look at this explanation in the FAQ.

Basic example using Sass

App.scss

.container {
  flex: 1;
  justify-content: center;
  align-items: center;
}

.blue {
  color: blue;
}

.blueText {
  @extend .blue;
  font-size: 18px;
}

App.js

import React from "react";
import { Text, View } from "react-native";
import styles from "./App.scss";

const App = () => (
  <View className={styles.container}>
    <Text className={styles.blueText}>Blue text</Text>
  </View>
);
export default App;

CSS media queries and CSS viewport units

If you need CSS media queries or CSS viewport units, please have a look at the responsive CSS features setup guide.

.wrapper {
  height: 10vh;
  width: 10vw;
}

@media (min-width: 800px) {
  .wrapper {
    height: 20vh;
    width: 20vw;
  }
}

CSS variables

CSS variables are not supported by default, but you can add support for them by using PostCSS and postcss-css-variables plugin.

Please have a look at the CSS variables setup guide.

:root {
  --text-color: blue;
}

.blue {
  color: var(--text-color);
}

Exporting variables from CSS to Javascript

You might also need to share you variables from a CSS/Sass/Less/Stylus file to Javascript. To do that you can use the :export keyword:

colors.scss

$grey: #ccc;

:export {
  grey: $grey;
}

App.js

import React from "react";
import { Text, View } from "react-native";
import colors from "./colors.scss";
import styles from "./App.scss";

const App = () => (
  <View className={styles.container}>
    <Text className={styles.blueText} style={{ color: colors.grey }}>
      Grey text
    </Text>
  </View>
);
export default App;

Example Apps

Have a look at the example apps to see how you can use CSS modules for both React Native and Web using the same code.

• Example app
• CSS Media Queries example app
• CSS Viewport Units example app
• Example app with styleName syntax
• Typescript example app

Documentation

📚 Setup

• Setup CSS modules with CSS support
• Setup CSS modules with PostCSS support
• Setup CSS modules with Sass support
• Setup CSS modules with Less support
• Setup CSS modules with Stylus support
• Setup CSS modules with Responsive CSS support (CSS Media Queries & CSS Viewport Units)
• Setup CSS modules with CSS variables support
• Setup CSS modules with Typescript support
• Setup CSS modules with styleName attribute (use className as a string)
• Use CSS and Sass in the same project
• Setup recommended linting (ESLint & stylelint)
• Setup browser compatibility

📚 Other documentation

• Frequently Asked Questions
• Stylelint config for React Native CSS modules
• List of CSS properties supported by React Native (out of date)

Development

To see which new features are being planned and what is in progress, please have a look at the development board.

If you want to suggest a new feature or report a bug, please open a new issue.

---

Special thanks

The idea for React Native CSS modules comes from these projects that have made a lot of work for supporting CSS and CSS modules in React Native: css-to-react-native and react-native-sass-classname. A big thanks to them!

---

License

MIT