Getting Started

Installation

React Native Small UI uses a modular architecture. Install only what you need to keep your bundle size minimal.

Core Package (Required)

The core package provides createComponent and essential utilities with minimal footprint (~5.7 KB gzipped).

yarn

yarn add react-native-small-ui

npm

npm install react-native-small-ui

pnpm

pnpm add react-native-small-ui

bun

bun add react-native-small-ui

Optional Features

Import additional features as needed through modular paths:

Core Only (~5.7 KB gz)

Basic component creation with platform-specific and color mode styling js import {createComponent} from 'react-native-small-ui';

+ Color Mode (~5.8 KB gz)

Programmatic theme switching and color mode utilities js import{' '} {useColorMode} from 'react-native-small-ui/colormode';

+ Responsive (~6.0 KB gz)

Breakpoints, media queries, and orientation detection js import{' '} {useBreakPointValue} from 'react-native-small-ui/utils';

+ Theme System (~6.2 KB gz)

Full theming with color utilities and semantic tokens js import{' '} {useTheme} from 'react-native-small-ui/theme';

Bundle Size

The modular import system ensures you only bundle what you use. See the Bundle Optimization guide for more details.

Web Support

React Native Web

---

Quick Start

Minimal Setup (Core Only)

Import createComponent and start building. The library auto-initializes on import — no setup hook required.

import * as React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { createComponent } from 'react-native-small-ui';

// Create styled components outside render
const Box = createComponent(View, {
  padding: 16,
  borderRadius: 8,
  _light: { backgroundColor: '#f5f5f5' },
  _dark: { backgroundColor: '#1a1a1a' },
  _ios: { shadowOpacity: 0.1 },
  _android: { elevation: 2 },
});

const Button = createComponent(TouchableOpacity, {
  padding: 12,
  borderRadius: 6,
  backgroundColor: '#007AFF',
  alignItems: 'center',
});

export default function App() {
  return (
    <View>
      <Box marginTop={112}>
        <Text>Hello Small UI!</Text>
        <Button>
          <Text style={{ color: '#fff' }}>Click me</Text>
        </Button>
      </Box>
    </View>
  );
}

With Color Mode

Add programmatic theme control:

import { createComponent } from 'react-native-small-ui';
import {
  useColorMode,
  toggleColorScheme,
} from 'react-native-small-ui/colormode';
import { View, Text, TouchableOpacity } from 'react-native';

const Box = createComponent(View, {
  padding: 16,
  _light: { backgroundColor: '#fff' },
  _dark: { backgroundColor: '#000' },
});

export default function ThemeToggle() {
  const { colorMode } = useColorMode();

  return (
    <Box>
      <Text>Current mode: {colorMode}</Text>
      <TouchableOpacity onPress={toggleColorScheme}>
        <Text>Toggle Theme</Text>
      </TouchableOpacity>
    </Box>
  );
}

With Responsive Utilities

Build responsive layouts:

import { createComponent } from 'react-native-small-ui';
import { useBreakPointValue } from 'react-native-small-ui/utils';
import { View, Text } from 'react-native';

const Box = createComponent(View, {
  backgroundColor: '#f5f5f5',
});

export default function ResponsiveBox() {
  const padding = useBreakPointValue({
    default: 8,
    sm: 12,
    md: 16,
    lg: 24,
  });

  return (
    <Box padding={padding}>
      <Text>Responsive padding based on screen size</Text>
    </Box>
  );
}

With Theme System

Register your own colors and access them via useTheme. The theme is shape-agnostic — store whatever your app needs:

import { createComponent } from 'react-native-small-ui';
import { registerTheme, useTheme } from 'react-native-small-ui/theme';
import { View, Text, TouchableOpacity } from 'react-native';

// Register at startup — any shape you want
registerTheme({
  light: { primary: '#007AFF', background: '#fff' },
  dark:  { primary: '#0A84FF', background: '#000' },
});

// Define your type once
type AppTheme = {
  light: { primary: string; background: string };
  dark:  { primary: string; background: string };
};

// Create component outside render
const Button = createComponent(TouchableOpacity, {
  borderRadius: 8,
  padding: 12,
});

function ThemedButton() {
  const theme = useTheme() as AppTheme;

  return (
    <Button
      _light={{ backgroundColor: theme.light.primary }}
      _dark={{ backgroundColor: theme.dark.primary }}
    >
      <Text style={{ color: '#fff' }}>Themed Button</Text>
    </Button>
  );
}

export default function ThemedButtonScreen() {
  return <ThemedButton />;
}

---

Next Steps

createComponent

Variants, slots, .extend(), and the reactive ctx API

Read More

Variant System

Type-safe variants, compound variants, and defaults

View Guide

Platform & Color Mode Registry

Custom platforms and app-managed color modes

View Guide

Helpers

cs(), getResolvedStyles(), getStatusBarStyle

View Helpers