CSS to React Native Style Transformer

3.2.0 · active · verified Sun Apr 19

css-to-react-native is a utility library that converts standard CSS-like style declarations into React Native stylesheet objects. Currently at version 3.2.0, it is actively maintained by the styled-components organization, indicating a stable release cadence. This library is essential for bridging web CSS styling conventions with React Native's unique styling model, automatically handling unit conversions, shorthand expansions, and platform-specific property transformations (e.g., `text-shadow-offset` to `{ width, height }`). A key differentiator is its ability to handle complex transformations like reversing `transform` order for React Native compatibility and expanding various shorthands such as `font` and `margin`. It focuses on transforming already parsed CSS property-value pairs, delegating the initial CSS parsing to external tools like PostCSS.

Common errors

```
No explicit error message, but output styles are incorrect or incomplete when processing CSS.
```
cause Attempting to pass raw CSS strings or manually parsing CSS with simple string manipulation methods (like `.split`) leading to incorrect `[property, value]` tuples.

fix Utilize a robust CSS parser (e.g., PostCSS, `stylis`) to reliably extract property-value pairs. `css-to-react-native` expects an array of `[property, value]` tuples as its input, not raw CSS strings.
```
A CSS shorthand property (e.g., `background`, `border`) does not produce the expected comprehensive React Native styles.
```
cause Shorthands are often limited to the subset of properties supported by React Native. For example, `background` only converts to `backgroundColor` as `backgroundImage` is not a direct RN style property.

fix Decompose complex CSS shorthands into individual, supported React Native style properties. Consult React Native's style documentation for specific property support.

Warnings

breaking As of v3.0.0, the library will now `console.warn` when units are omitted on properties that require them (e.g., `top`, `width`).
Fix: Ensure all properties requiring units have them explicitly defined (e.g., `width: '10px'` instead of `width: 10`).
breaking Unitless `line-height` is no longer supported within the `font` shorthand as of v3.0.0.
Fix: Provide `line-height` values with explicit units (e.g., `font: '14px/16px Helvetica'` instead of `font: '14px/1.5 Helvetica'`).
gotcha The `box-shadow` CSS shorthand only converts to `shadow-` properties which are exclusively supported on iOS in React Native.
Fix: Be aware that `box-shadow` styles will not render on Android. Consider platform-specific styling or alternative visual effects for cross-platform support.
gotcha Individual `border{Top,Right,Bottom,Left}` shorthands are not supported due to limitations in applying `borderStyle` to individual border sides in React Native.
Fix: Use individual properties like `borderTopWidth`, `borderTopColor`, `borderTopLeftRadius`, etc., for precise border styling.
gotcha Complex `transform` values are automatically reordered by `css-to-react-native` to match React Native's inverse application order.
Fix: No manual fix required, but developers should be aware that the internal transformation order might differ from web CSS to ensure correct visual output in React Native.

Install

npm install css-to-react-native npm
yarn add css-to-react-native yarn
pnpm add css-to-react-native pnpm

Imports

transform
wrong:
```
const transform = require('css-to-react-native');
```
correct:
```
import transform from 'css-to-react-native';
```
The primary default export for converting CSS property-value tuples. For CommonJS, explicitly access the '.default' property as shown in the package's documentation to avoid undefined values.
getPropertyName
wrong:
```
const getPropertyName = require('css-to-react-native').getPropertyName;
```
correct:
```
import { getPropertyName } from 'css-to-react-native';
```
Named export for converting a dashed CSS property name (e.g., 'border-width') to its camelCase React Native equivalent ('borderWidth'). Available since v1.
getStylesForProperty
wrong:
```
const getStylesForProperty = require('css-to-react-native').getStylesForProperty;
```
correct:
```
import { getStylesForProperty } from 'css-to-react-native';
```
Named export for transforming a single CSS property and value into a React Native style object. Useful for advanced implementors or custom parsing scenarios.

Quickstart

Demonstrates converting an array of CSS property-value tuples, including shorthands and complex values, into a React Native stylesheet object. Shows how `transform` order is handled.

import transform from 'css-to-react-native';

const cssStyleTuples = [
  ['font', 'bold 14px/16px "Helvetica"'],
  ['margin', '5px 7px 2px'],
  ['border-left-width', '5px'],
  ['text-shadow-offset', '10px 5px'],
  ['transform', 'translate(10px, 5px) scale(2) rotate(45deg)']
];

const reactNativeStyles = transform(cssStyleTuples);

console.log(reactNativeStyles);
/*
Expected output similar to:
{
  fontFamily: 'Helvetica',
  fontSize: 14,
  fontWeight: 'bold',
  fontStyle: 'normal',
  fontVariant: [],
  lineHeight: 16,
  marginTop: 5,
  marginRight: 7,
  marginBottom: 2,
  marginLeft: 7,
  borderLeftWidth: 5,
  textShadowOffset: { width: 10, height: 5 },
  transform: [
    { rotate: '45deg' },
    { scale: 2 },
    { translateY: 5 },
    { translateX: 10 }
  ]
}
*/

view raw JSON →