react-native-blueprint

A production-ready React Native UI component library built with NativeWind (Tailwind CSS) and shadcn/ui design patterns. Features 35+ fully customizable, accessible components for iOS, Android, and Web.

Features

• 🎨 35+ Components - Complete UI kit including buttons, forms, overlays, navigation, and data display
• 🌓 Dark Mode - Built-in theme support with CSS variables
• ♿ Accessible - ARIA-compliant components with screen reader support
• 📱 Cross-Platform - Works seamlessly on iOS, Android, and Web
• 🎯 Type-Safe - Full TypeScript support with IntelliSense
• 🚀 NativeWind - Tailwind CSS styling for React Native
• 🔧 Customizable - Easy to theme and extend with Tailwind utilities
• ⚡ Performant - Built on React Native Reanimated for smooth animations

⚠️ Prerequisites

This library requires NativeWind v4+ to be configured in your React Native project. NativeWind provides Tailwind CSS styling for React Native.

Not using NativeWind? This library is designed specifically for NativeWind-based projects. If you're not using NativeWind, you'll need to configure it first or consider an alternative component library.

Installation

This library works with both Expo and Bare React Native CLI projects. Choose the installation method for your project type.

Quick Start

# Install the package
npm install @campxdev/react-native-blueprint
# or
yarn add @campxdev/react-native-blueprint

# Install required peer dependencies (minimum)
npm install @rn-primitives/slot @rn-primitives/types nativewind tailwindcss tailwindcss-animate
# or
yarn add @rn-primitives/slot @rn-primitives/types nativewind tailwindcss tailwindcss-animate

Note: Only install the @rn-primitives packages for components you actually use. See the Component Dependencies table below.

For Bare React Native CLI Projects (Recommended)

Perfect for apps like CampxMobileApp using React Native CLI without Expo.

1. Install the package

npm install @campxdev/react-native-blueprint
# or
yarn add @campxdev/react-native-blueprint

2. Install required peer dependencies

npm install nativewind tailwindcss tailwindcss-animate react-native-reanimated react-native-gesture-handler react-native-svg react-native-safe-area-context react-native-screens
# or
yarn add nativewind tailwindcss tailwindcss-animate react-native-reanimated react-native-gesture-handler react-native-svg react-native-safe-area-context react-native-screens

3. Install optional peer dependencies (as needed)

# For bottom sheet components (optional)
npm install @gorhom/bottom-sheet

# For advanced animations (optional)
npm install react-native-worklets

# For specific UI primitives (install only what you need)
npm install @rn-primitives/accordion @rn-primitives/dialog @rn-primitives/avatar
# ... add other @rn-primitives packages as needed

4. For iOS, install CocoaPods

cd ios && pod install && cd ..

5. Add Reanimated Babel plugin

Update your babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'react-native-reanimated/plugin', // Must be listed last!
  ],
};

For Expo Projects

If you're using Expo, the installation is simpler:

1. Install the package and peer dependencies

npx expo install @campxdev/react-native-blueprint nativewind tailwindcss tailwindcss-animate react-native-reanimated react-native-gesture-handler react-native-svg
# Expo will automatically install compatible versions

2. Install optional fonts (for custom fonts)

npx expo install expo-font @expo-google-fonts/poppins @expo-google-fonts/heebo

Then load fonts in your app:

import { useFonts } from 'expo-font';
import { Poppins_400Regular, Poppins_600SemiBold } from '@expo-google-fonts/poppins';

function App() {
  const [fontsLoaded] = useFonts({ Poppins_400Regular, Poppins_600SemiBold });
  if (!fontsLoaded) return null;
  // Your app
}

Common Setup (Required for Both)

Import the global styles

In your app entry point (e.g., App.tsx or _layout.tsx):

import '@campxdev/react-native-blueprint/global.css';

Configure NativeWind

Create or update tailwind.config.js:

const { hairlineWidth } = require('nativewind/theme');

module.exports = {
  darkMode: 'class',
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@campxdev/react-native-blueprint/src/**/*.{ts,tsx}',
  ],
  presets: [require('nativewind/preset')],
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))',
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))',
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))',
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))',
        },
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))',
        },
      },
      borderWidth: {
        hairline: hairlineWidth(),
      },
    },
  },
  plugins: [require('tailwindcss-animate')],
};

Configure Bundler (Metro or Re.Pack)

For Expo Projects:

Update metro.config.js:

const { getDefaultConfig } = require('expo/metro-config');
const { withNativeWind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withNativeWind(config, { input: './global.css' });

For Bare React Native CLI Projects:

Update metro.config.js:

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withNativeWind } = require('nativewind/metro');

const config = mergeConfig(getDefaultConfig(__dirname), {
  // Your custom Metro config
});

module.exports = withNativeWind(config, { input: './global.css' });

Alternative: Re.Pack + Rspack (5x Faster - Used in Example App)

The example app in this repository uses Re.Pack 5 with Rspack for 5x faster builds. See MIGRATION_REPACK.md for details.

If you want to use Re.Pack in your project:

1. Install Re.Pack:

   npx @callstack/repack-init

2. Install NativeWind plugin:

   npm install @callstack/repack-plugin-nativewind

3. Update rspack.config.js:

   import { NativeWindPlugin } from '@callstack/repack-plugin-nativewind';
   
   export default (env) => ({
     // ... other config
     plugins: [
       new NativeWindPlugin({
         input: './global.css',
       }),
     ],
   });

Usage

The library supports two import methods:

Option 1: Main Package Import (Core Components Only)

Import core components from the main package. The main barrel export only includes components with minimal dependencies to avoid forcing you to install all @rn-primitives packages.

Core components available from main import:

• Alert, AppBar, Badge, Button, Card, Custom-Card, Floating-Action, Greeting-Card, Icon, Input, Native-Only-Animated-View, NavBar, Separator, SizedBox, Skeleton, Table, Text, Textarea, Theme-Toggle

// Import CSS at the top of your app entry point (do this ONCE)
import '@campxdev/react-native-blueprint/global.css';

import {
  Button,
  Card,
  Text,
  Input,
  Alert,
  Badge,
  Skeleton,
} from '@campxdev/react-native-blueprint';
import { View } from 'react-native';

function App() {
  return (
    <View className="flex-1 p-4 bg-background">
      <Card>
        <Card.Header>
          <Card.Title>Welcome</Card.Title>
          <Card.Description>
            Get started with react-native-blueprint
          </Card.Description>
        </Card.Header>
        <Card.Content>
          <Input placeholder="Enter your name" />
        </Card.Content>
        <Card.Footer>
          <Button>
            <Text>Submit</Text>
          </Button>
        </Card.Footer>
      </Card>

      <Alert>
        <Alert.Title>Info</Alert.Title>
        <Alert.Description>This is a sample alert component.</Alert.Description>
      </Alert>
    </View>
  );
}

Option 2: Tree-Shakeable Imports (For All Components)

For components requiring @rn-primitives (like Accordion, Dialog, Checkbox, etc.), you must use tree-shakeable imports. This also works for core components and provides the best bundle size.

// Import CSS at the top of your app entry point (do this ONCE)
import '@campxdev/react-native-blueprint/global.css';

// Core components (also available from main import)
import { Button } from '@campxdev/react-native-blueprint/Button';
import { Card } from '@campxdev/react-native-blueprint/Card';
import { Text } from '@campxdev/react-native-blueprint/Text';
import { Input } from '@campxdev/react-native-blueprint/Input';
import { Alert } from '@campxdev/react-native-blueprint/Alert';

// Components requiring @rn-primitives (MUST use tree-shakeable imports)
import { Dialog } from '@campxdev/react-native-blueprint/Dialog';
import { Checkbox } from '@campxdev/react-native-blueprint/Checkbox';
import { Avatar } from '@campxdev/react-native-blueprint/Avatar';

import { View } from 'react-native';

function App() {
  return (
    <View className="flex-1 p-4 bg-background">
      <Card>
        <Card.Header>
          <Card.Title>Welcome</Card.Title>
          <Card.Description>
            Get started with react-native-blueprint
          </Card.Description>
        </Card.Header>
        <Card.Content>
          <Input placeholder="Enter your name" />
        </Card.Content>
        <Card.Footer>
          <Button>
            <Text>Submit</Text>
          </Button>
        </Card.Footer>
      </Card>

      <Alert>
        <Alert.Title>Info</Alert.Title>
        <Alert.Description>This is a sample alert component.</Alert.Description>
      </Alert>
    </View>
  );
}

Available Components

Layout & Structure

• Button - Customizable button with variants (default, destructive, outline, ghost, link)
• Card - Container with header, content, and footer sections
• Separator - Horizontal or vertical divider
• Skeleton - Loading placeholder with shimmer effect

Form Components

• Input - Text input field
• Textarea - Multi-line text input
• Checkbox - Checkbox with label support
• Radio Group - Radio button group
• Switch - Toggle switch
• Select - Dropdown select menu
• Label - Form field label
• Slider - Range slider input

Navigation

• Tabs - Tab navigation component
• Accordion - Collapsible content sections
• Collapsible - Expandable/collapsible content
• Menubar - Menu bar with nested items

Overlays & Dialogs

• Dialog - Modal dialog
• Alert Dialog - Alert/confirmation dialog
• Popover - Floating popover
• Tooltip - Hover tooltip
• Dropdown Menu - Context menu dropdown
• Context Menu - Right-click context menu
• Hover Card - Card that appears on hover

Feedback & Status

• Alert - Informational alert box
• Toast - Toast notification
• Progress - Progress bar
• Badge - Status badge

Data Display

• Table - Data table with sorting
• Avatar - User avatar with fallback
• Text - Typography component with variants
• Icon - Icon component (powered by lucide-react-native)

Utilities

• Aspect Ratio - Container with fixed aspect ratio
• Toggle - Toggle button
• Toggle Group - Group of toggle buttons

Component Dependencies

All peer dependencies are optional - only install what you need based on the components you use.

Core Dependencies (Required for Most Components)

npm install @rn-primitives/slot @rn-primitives/types

Component-Specific Dependencies

| Component | Required Packages | Notes | |-----------|------------------|-------| | Accordion | @rn-primitives/accordion@rn-primitives/collapsible | Collapsible content sections | | Alert | None | Always available | | Alert-Dialog | @rn-primitives/alert-dialog@rn-primitives/portal | Confirmation dialogs | | AppBar | None | Always available | | Aspect-Ratio | @rn-primitives/aspect-ratio | Fixed aspect ratio containers | | Avatar | @rn-primitives/avatar | User avatars with fallback | | Badge | None | Always available | | Bottom-Sheet | @gorhom/bottom-sheetreact-native-reanimatedreact-native-gesture-handler | Bottom sheet modals | | Button | @rn-primitives/slot | Always available with slot | | Card | None | Always available | | Checkbox | @rn-primitives/checkbox | Checkbox inputs | | Collapsible | @rn-primitives/collapsible | Expandable content | | Context-Menu | @rn-primitives/context-menu | Right-click menus | | Custom-Card | None | Always available | | Dialog | @rn-primitives/dialog@rn-primitives/portal | Modal dialogs | | Dropdown-Menu | @rn-primitives/dropdown-menu | Dropdown menus | | Floating-Action | react-native-floating-action | Floating action button | | Greeting-Card | None | Always available | | Hover-Card | @rn-primitives/hover-card | Hover-triggered cards | | Icon | lucide-react-nativereact-native-svg | Icon library | | Input | None | Always available | | Label | @rn-primitives/label | Form labels | | Menubar | @rn-primitives/menubar | Menu bars | | Native-Only-Animated-View | react-native-reanimated | Animated views | | NavBar | None | Always available | | Popover | @rn-primitives/popover | Floating popovers | | Progress | @rn-primitives/progress | Progress bars | | Radio-Group | @rn-primitives/radio-group | Radio button groups | | Select | @rn-primitives/select | Dropdown selects | | Separator | None | Always available | | SizedBox | None | Always available | | Skeleton | None | Always available (loading states) | | Slider | @rn-primitives/slider | Range sliders | | Switch | @rn-primitives/switch | Toggle switches | | Table | None | Always available | | Tabs | @rn-primitives/tabs | Tab navigation | | Text | None | Always available | | Textarea | None | Always available | | Theme-Toggle | None | Always available | | Toast | Custom implementation | Toast notifications | | Toggle | @rn-primitives/toggle | Toggle buttons | | Toggle-Group | @rn-primitives/toggle-group | Toggle button groups | | Tooltip | @rn-primitives/tooltip | Hover tooltips |

Install All Optional Dependencies (For All Components)

If you want to use all components without worrying about individual dependencies:

npm install @rn-primitives/accordion @rn-primitives/alert-dialog @rn-primitives/aspect-ratio @rn-primitives/avatar @rn-primitives/checkbox @rn-primitives/collapsible @rn-primitives/context-menu @rn-primitives/dialog @rn-primitives/dropdown-menu @rn-primitives/hover-card @rn-primitives/label @rn-primitives/menubar @rn-primitives/popover @rn-primitives/portal @rn-primitives/progress @rn-primitives/radio-group @rn-primitives/select @rn-primitives/separator @rn-primitives/slider @rn-primitives/slot @rn-primitives/switch @rn-primitives/tabs @rn-primitives/toggle @rn-primitives/toggle-group @rn-primitives/tooltip @rn-primitives/types @gorhom/bottom-sheet react-native-worklets

Theming

Components use CSS variables for theming. Customize your app's appearance by modifying the CSS variables in global.css:

:root {
  --primary: 220 90% 56%; /* Blue */
  --secondary: 280 70% 60%; /* Purple */
  --destructive: 0 84% 60%; /* Red */
  --radius: 0.75rem; /* Border radius */
}

Dark Mode

Toggle dark mode by adding/removing the dark class on your root element:

import { useColorScheme } from 'react-native';

function App() {
  const colorScheme = useColorScheme();

  return (
    <View className={colorScheme === 'dark' ? 'dark' : ''}>
      {/* Your app */}
    </View>
  );
}

Example App

Check out the /example directory for a complete demo app showcasing all components with Storybook integration and Re.Pack + Rspack for 5x faster builds.

Run Normal App Mode

yarn example:app        # From root (recommended)
# or
cd example
yarn app:ios            # Run on iOS simulator
yarn app:android        # Run on Android emulator

Run Storybook Mode

The example app includes 16 interactive component stories using Storybook for React Native:

yarn example:storybook  # From root (recommended)
# or
cd example
yarn storybook:ios      # Run Storybook on iOS
yarn storybook:android  # Run Storybook on Android

Build Performance

The example app uses Re.Pack 5 + Rspack instead of Metro for:

• ⚡ 5x faster cold builds
• ⚡ 5x faster hot module reload (HMR)
• 📦 Zero package duplications
• 🎨 Full NativeWind support

See MIGRATION_REPACK.md for complete migration details and architecture.

TypeScript Support

All components are fully typed with TypeScript. Import types as needed:

import type { ButtonProps, CardProps } from '@campxdev/react-native-blueprint';

Troubleshooting

"Cannot find module '@campxdev/react-native-blueprint/global.css'"

Make sure you've:

1. Installed NativeWind: npm install nativewind tailwindcss
2. Configured Metro with NativeWind plugin (see Installation Step 5)
3. Imported the CSS in your app entry point

"CSS import is not supported"

Your Metro bundler needs the NativeWind plugin. Update metro.config.js:

const { getDefaultConfig } = require('expo/metro-config');
const { withNativeWind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withNativeWind(config, { input: './global.css' });

Components not styling correctly

Ensure your tailwind.config.js includes the package path in the content array:

content: [
  './src/**/*.{ts,tsx}',
  './node_modules/@campxdev/react-native-blueprint/src/**/*.{ts,tsx}',
],

Migration Guides

Migration from v0.1.x to v0.2.x

Breaking Changes:

1. CSS must now be manually imported
2. Expo is no longer a direct dependency (but still supported!)
3. Many dependencies moved to peer dependencies

What changed?

v0.1.x:

• Included Expo as direct dependency
• CSS auto-imported via RootLayout
• All packages bundled as direct dependencies

v0.2.x:

• ✅ Works with both Expo and bare React Native CLI
• ✅ CSS must be explicitly imported (better tree-shaking)
• ✅ Most packages are now peer dependencies (smaller bundle, less conflicts)
• ✅ CommonJS and ESM support (fixes module warnings)

Migration Steps

For ALL Projects (Expo & Bare RN CLI)

1. Add CSS import to your app entry point (e.g., App.tsx or _layout.tsx):

import '@campxdev/react-native-blueprint/global.css';

2. Install peer dependencies:

# Required peer dependencies
npm install nativewind tailwindcss tailwindcss-animate react-native-reanimated react-native-gesture-handler react-native-svg react-native-safe-area-context react-native-screens

# Optional (install as needed)
npm install @gorhom/bottom-sheet react-native-worklets
npm install @rn-primitives/accordion @rn-primitives/dialog # ... etc

For Expo Projects ONLY

3. Install Expo-specific packages (if you want custom fonts):

npx expo install expo-font @expo-google-fonts/poppins @expo-google-fonts/heebo

For Bare React Native CLI ONLY

3. Add Reanimated plugin to babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'react-native-reanimated/plugin', // Must be last!
  ],
};

4. For iOS, run pod install:

cd ios && pod install && cd ..

Font Handling Changes

v0.1.x: Fonts were loaded via Expo automatically

v0.2.x:

• Uses system fonts by default (works everywhere!)
• Expo users can still use expo-font (see installation guide)
• Bare RN CLI users can add custom fonts manually (see fonts.ts documentation)

That's it! Your app should work as before with better compatibility.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Workflow

1. Clone the repo and install dependencies:

   git clone https://github.com/campx-org/react-native-blueprint.git
   cd react-native-blueprint
   yarn install

2. Run the example app:

   Normal App Mode:

   yarn example:app          # Start dev server
   cd example && yarn app:ios     # Or run on iOS
   cd example && yarn app:android # Or run on Android

   Storybook Mode (Component Library):

   yarn example:storybook         # Start Storybook
   cd example && yarn storybook:ios      # Or run on iOS
   cd example && yarn storybook:android  # Or run on Android

3. Make your changes in /src

4. Run type checking and linting:

   yarn typecheck
   yarn lint

5. Build the library:

   yarn prepare

Example App Tech Stack

The example app showcases modern React Native development with:

• Re.Pack 5 + Rspack - 5x faster than Metro bundler
• Storybook React Native - Interactive component development
• NativeWind v4 - Tailwind CSS for React Native
• Command-based mode switching - Easy switching between app and Storybook modes

License

MIT © CAMPX

Credits

• Built with create-react-native-library
• Inspired by shadcn/ui
• Styled with NativeWind
• Primitives from @rn-primitives

Support

• GitHub Issues: Report a bug
• Discussions: Ask questions

Made with ❤️ by CAMPX