- Notifications
You must be signed in to change notification settings - Fork0
License
salemkode/react-native-css
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A CSS polyfill for React Native
The goal of this library is to provide the most complete CSS support for React Native, within the limitations of Yoga and the core React Native package. This includes multiple advanced CSS features like media queries, container queries, CSS variables, and more.
- Create a CSS file in your project, e.g.
styles.css. - Import the CSS file in your App entry point, or root layout component:
- Setup the bundler using one of the methods below.
Tip
Most React Native projects use Metro as the bundler.
You will need to addwithReactNativeCSS to your Metro configuration.
import{getDefaultConfig}from"expo/metro-config";import{withReactNativeCSS}from"react-native-css/metro";constdefaultConfig=getDefaultConfig(__dirname);exportdefaultwithReactNativeCSS(defaultConfig);// OR with the globalClassNamePolyfill enabledexportdefaultwithReactNativeCSS(defaultConfig,{globalClassNamePolyfill:true,});
react-native-css relies on the bundler to process CSS files. Currently only Expo provides a CSS asset pipeline. Since the Expo SDK is modular, you can add this functionality by just using the@expo/metro-config package.
Follow the Expo instructions, but replace theexpo package with@expo/metro-config.
- import { getDefaultConfig } from "expo/metro-config";+ import { getDefaultConfig } from "@expo/metro-config";
react-native-css officially only supports Metro as the bundler, but we welcome community contributions to support other bundlers like Webpack, Vite or Turbopack.
More documentation coming soon.
You can use the library by importing the React Native components directly fromreact-native-css/components:
import{View}from'react-native-css/components';import"./styles.css";exportdefaultfunctionApp(){return(<ViewclassName="container"><ViewclassName="box"/></View>);}
Enabling theglobalClassNamePolyfill allows you to use the classNames prop on any React Native component, similar to how you would use it in a web application.
import{View}from'react-native';import"./styles.css";exportdefaultfunctionApp(){return(<ViewclassName="container"><ViewclassName="box"/></View>);}
To enable theglobalClassNamePolyfill, you need to enable it in your Metro configuration:
import{withReactNativeCSS}from"react-native-css/metro";module.exports=withReactNativeCSS({// Your existing Metro configuration},{globalClassNamePolyfill:true,},);
You can also use thestyled function to get styled components.
import{View}from'react-native';import{styled}from'react-native-css';import"./styles.css";constMyView=styled(View)exportdefaultfunctionApp(){return(<MyViewclassName="container"><MyViewclassName="box"/></View>);}
You can also use theuseCssElement hook.
import{View}from'react-native';import{useCssElement}from'react-native-css';exportdefaultfunctionApp(){constContainer=useCssElement(View,{className:"container",});constBox=useCssElement(View,{className:"box",});return(<Container><Box/></Container>);}
Important
The hook returns a React Element, not a style object.
If you just require the style object, you can use theuseNativeCssStyle hook
import{ViewasRNView}from'react-native';import{useNativeCssStyle}from'react-native-css';import"./styles.css";exportdefaultfunctionApp(){return(<Viewstyle={useNativeCssStyle("container")}><Textstyle={useNativeCssStyle("my-text")}>Hello,world!</Text></View>)}
Important
This hook may will only work on native platforms. It will return an empty object on web.This hook may not support all features of the library.This hooks does not support container queries or inheritance for children elements.
If you just require a CSS variable value, you can use theuseNativeCssVariable hook:
import{useNativeCssVariable}from'react-native-css';exportdefaultfunctionApp(){constmyColor=useNativeCssVariable("--my-color");return(<Viewstyle={{backgroundColor:myColor}}><Textstyle={{color:myColor}}>Hello,world!</Text></View>)}
Important
This hook may will only work on native platforms. It will returnundefined on web.This hook may not support all features of the library.
It is preferable that all CSS variables are set via CSS. If you need values to change dynamically, we recommend using a class to change the values.
.theme-red {--brand-color: red;}.theme-blue {--brand-color: blue;}
As a last resort, you can useVariableContext to dynamically set CSS variables in JavaScript
import{VariableContext}from'react-native-css';exportdefaultfunctionApp(){return(<VariableContextvalues={{"--my-color":"red"}}><TextclassName="my-color-text">Hello,world!</Text></VariableContext>)}
This API only allows for setting CSS variables as primitive values. For more complex styles, you will need to use a helper CSS class.
Important
By usingVariableContext you may need to disable theinlineVariable optimization
CSS is a dynamic styling language that use highly optimized engines that are not available in React Native. Instead, we optimize the styles to improve performance
These optimizations are only applied in native environments and are enabled by default.
Allrem units are converted todp units at build time. On native, the default dp is 14. You can change the defaultrem by passing ainlineRem option to thewithReactNativeCSS function.
exportdefaultwithReactNativeCSS(defaultConfig,{inlineRem:16,// change to 16dp,});
Custom properties (sometimes referred to as CSS variables or cascading variables) are a way to store values that can be reused throughout a CSS document. They are defined using a property name that starts with--, and their values can be accessed using thevar() function.
To improve performance, Custom properties that are only setonce in the CSS file are inlined at build time.
For example
:root {--my-var: red;--var-with-two-possible-values: blue;}.my-class {--var-with-two-possible-values: green;color:var(--my-var);background-color:var(--var-with-two-possible-values);}
Is converted to:
:root {--var-with-two-possible-values: blue;}.my-class {color: red;/* This was inlined and the variable was removed *//* These are preserved as there are multiple possible values */--var-with-two-possible-values: green;background-color:var(--var-with-two-possible-values);}
UsingVariableContext withinlineVariables may have unexpected results, as rules may have been rewritten not to use a variable. You can disable this behavior by settinginlineVariables: false
exportdefaultwithReactNativeCSS(defaultConfig,{inlineVariables:false,});
See thecontributing guide to learn how to contribute to the repository and the development workflow.
To quickly get started with the project, you can run:
yarn init -2# We require Yarn 4yarn clean# Install dependencies, rebuild the project and example appyarn example ios# Or yarn example android
Once the example app is built, you can use
yarn example start# Start Expo CLIyarn example start:build# Rebuild the project and start Expo CLIyarn example start:debug# Rebuild the project and start Expo CLI with debug logging
Tip
start:build andstart:debug will clear the cache before starting the Expo CLI. If you are experiencing issue withyarn example start not reflecting your changes, try runningyarn example start:build oryarn example start:debug.
MIT
See thelicense file for more details.
Made withcreate-react-native-library
About
Resources
License
Code of conduct
Contributing
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Languages
- TypeScript98.9%
- Other1.1%