Skip to main content

​
Overview

The useCssElement hook allows you to create React Native components with CSS-based styling. It’s a low-level primitive from react-native-css that NativeWind uses internally to apply styles based on CSS classes and enable advanced styling features.

​
Import

import { useCssElement } from 'nativewind';

​
Type Signature

function useCssElement(
  Component: React.ComponentType,
  props: Record<string, any>,
  ref?: React.Ref<any>
): React.ReactElement

​
Parameters

​
Component
React.ComponentType
required
The React Native component to wrap with CSS styling capabilities. Can be any valid React Native component like View, Text, Pressable, etc.
​
props
Record<string, any>
required
The props object to pass to the component, including style-related props like className, style, and any component-specific props.
​
ref
React.Ref<any>
Optional ref to forward to the underlying component. Useful when you need direct access to the component instance.

​
Return Value

​
element
React.ReactElement
A React element with CSS-based styling applied. The element will respond to CSS classes, CSS variables, and other styling features provided by react-native-css.

​
Usage

import { View, Text } from 'react-native';
import { useCssElement } from 'nativewind';

function CustomCard({ children, ...props }) {
  return useCssElement(
    View,
    {
      className: 'bg-white p-4 rounded-lg shadow-md',
      ...props,
    }
  );
}

export default function App() {
  return (
    <CustomCard>
      <Text className="text-lg font-bold">Card Title</Text>
      <Text className="text-gray-600">Card content goes here</Text>
    </CustomCard>
  );
}

​
Advanced Features

​
CSS Variables Support

Components created with useCssElement automatically support CSS variables: 
import { View, Text } from 'react-native';
import { useCssElement } from 'nativewind';

function ThemedCard({ children }) {
  return useCssElement(
    View,
    {
      className: 'bg-[var(--card-bg)] p-4 rounded-lg',
      style: {
        '--card-bg': '#ffffff',
      },
      children,
    }
  );
}

​
Responsive Styles

The hook works seamlessly with Tailwind’s responsive modifiers: 
function ResponsiveContainer({ children }) {
  return useCssElement(
    View,
    {
      className: 'p-4 sm:p-6 md:p-8 lg:p-12',
      children,
    }
  );
}

​
State-Based Styling

Combine with React state for dynamic styling: 
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { useCssElement } from 'nativewind';

function ToggleButton() {
  const [isActive, setIsActive] = useState(false);

  return useCssElement(
    Pressable,
    {
      className: isActive
        ? 'bg-green-500 px-6 py-3 rounded'
        : 'bg-gray-300 px-6 py-3 rounded',
      onPress: () => setIsActive(!isActive),
      children: (
        <Text className={isActive ? 'text-white' : 'text-gray-700'}>
          {isActive ? 'Active' : 'Inactive'}
        </Text>
      ),
    }
  );
}

​
Best Practices

When to use useCssElement:
  • Creating custom component libraries that need CSS styling
  • Building reusable styled primitives
  • When you need fine-grained control over component rendering
  • Wrapping third-party components to add NativeWind support
Performance Consideration:While useCssElement is powerful, for most cases the standard className prop on NativeWind-enabled components is more performant and easier to use. Use this hook when you need the additional control it provides.
  1. Memoize component wrappers to avoid unnecessary re-renders:
const StyledView = memo(({ className, ...props }) => {
  return useCssElement(View, { className, ...props });
});
  1. Extract reusable styled components into separate files:
// components/StyledButton.tsx
export function StyledButton({ variant, ...props }) {
  return useCssElement(Pressable, {
    className: getVariantClasses(variant),
    ...props,
  });
}
  1. Combine with TypeScript for type safety:
interface ButtonProps extends PressableProps {
  variant?: 'primary' | 'secondary' | 'danger';
}

const Button: React.FC<ButtonProps> = ({ variant = 'primary', ...props }) => {
  return useCssElement(Pressable, { className: getClasses(variant), ...props });
};