react-native-atomic-ui

A zero-dependency atomic UI component library for React Native with built-in dark mode support.

✨ Features

• ✅ 30+ Core Components - Ready-to-use UI building blocks with zero external dependencies
• ✅ TypeScript First - Full type definitions, strict mode enabled
• ✅ Dark Mode Built-in - Light/dark themes with system preference detection
• ✅ Context-Based Theme - Pure React Context with system preference support
• ✅ Small Bundle - ~50-80 KB minified core library
• ✅ Modular Architecture - Import only what you need
• ✅ Platform Support - iOS 12.0+, Android 6.0+
• ✅ React Native 0.73.0+ - Broad ecosystem compatibility

📦 Core Components (Zero Dependencies)

Layout Components

• Box - Flexible container with theme-aware spacing
• Row - Horizontal flex container
• Column - Vertical flex container
• Collapsible - Expandable/collapsible sections

Typography Components

• Text - Base text component with theme variants
• H1, H2, H3, H4, H5, H6 - Heading levels
• Body1 - Body6 - Body text variants
• SubTitle1, SubTitle2 - Subtitle components
• Caption, Overline - Small text variants

Input Components

• Button - Multi-variant buttons (primary, secondary, danger, ghost)
• Input - Text input with theme support
• FloatingInput - Floating label text input
• BorderedInput - Bordered text input variant
• InputNumber - Numeric input with validation
• RadioButton / RadioGroup - Radio selection
• CheckBox - Checkbox component
• CheckBoxMultiPicker - Multi-select checkboxes

Display Components

• ScaledImage - Responsive image container
• PaginatedFlatList - Lazy-loaded list with pagination
• PasswordReport - Password strength indicator
• ShowMoreText - Expandable text display
• HorizontalProgressBar - Progress bar component

🚀 Installation

Basic Setup

npm install react-native-atomic-ui
# or
yarn add react-native-atomic-ui

Note: react and react-native are peer dependencies and should already be installed in your React Native project.

iOS Additional Setup

After installation, if you're on iOS, install pods:

cd ios && pod install && cd ..

📱 Example App

Want to see all components in action? Check out our comprehensive showcase app:

👉 AtomicUIApp Example - A complete React Native app demonstrating all components, themes, and features.

To run the example app:

cd examples/app
npm install
cd ios && pod install && cd ..
npx react-native run-ios  # or run-android

🔧 Quick Start

1. Install the Package

npm install react-native-atomic-ui

2. Setup Theme Provider

Wrap your app with ThemeProvider at the root level (usually in index.js or App.tsx):

import React from 'react';
import { ThemeProvider } from 'react-native-atomic-ui';
import { App } from './App';

export function Root() {
  return (
    <ThemeProvider>
      <App />
    </ThemeProvider>
  );
}

3. Start Using Components

import React from 'react';
import {
  Box,
  Column,
  Button,
  H1,
  Body1,
  useTheme,
} from 'react-native-atomic-ui';

export function MyScreen() {
  const { theme, isDark, toggleTheme } = useTheme();

  return (
    <Box padding="lg" backgroundColor={theme.colors.background}>
      <Column gap="md">
        <H1>Welcome to Atomic UI</H1>
        <Body1>This is a beautiful, themeable UI library.</Body1>

        <Button
          label={isDark ? '☀️ Light Mode' : '🌙 Dark Mode'}
          onPress={toggleTheme}
          variant="primary"
          size="large"
        />
      </Column>
    </Box>
  );
}

🎨 Theme & Customization

Light/Dark Modes

The library automatically detects system color scheme and provides both light and dark themes:

import { useTheme } from 'react-native-atomic-ui';

export function ThemedComponent() {
  const { theme, isDark, toggleTheme } = useTheme();

  return (
    <Box backgroundColor={theme.colors.background}>
      {/* Your content */}
      <Button
        label="Toggle Theme"
        onPress={toggleTheme}
      />
    </Box>
  );
}

Accessing Theme Colors

const { theme } = useTheme();

// Primary colors
theme.colors.primary      // Main brand color
theme.colors.secondary    // Secondary brand color
theme.colors.error        // Error/danger red
theme.colors.success      // Success green
theme.colors.warning      // Warning orange

// Neutral colors
theme.colors.background   // Page background
theme.colors.surface      // Surface elements
theme.colors.text         // Primary text
theme.colors.textSecondary // Secondary text
theme.colors.border       // Borders

// And many more...

Spacing System

The theme includes a consistent spacing scale:

const { theme } = useTheme();

theme.spacing.xs   // 4px
theme.spacing.sm   // 8px
theme.spacing.md   // 16px
theme.spacing.lg   // 24px
theme.spacing.xl   // 32px
theme.spacing.xxl  // 48px

Typography

Use named variants for consistent typography:

import { H1, Body1, Caption, Text, useTheme } from 'react-native-atomic-ui';

export function TypographyExample() {
  const { theme } = useTheme();

  return (
    <Column gap="md">
      <H1>Heading 1 - 48px</H1>
      <Body1>Body text - 16px</Body1>
      <Caption>Caption - 12px</Caption>
      <Text variant="subtitle1">Custom variant</Text>
      <Text
        variant="body2"
        color={theme.colors.textSecondary}
      >
        Custom color
      </Text>
    </Column>
  );
}

📚 Component API Reference

Layout Components

Box

Flexible container component for layout with theme-aware spacing.

interface BoxProps {
  children?: React.ReactNode;
  padding?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  paddingHorizontal?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  paddingVertical?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  margin?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  marginHorizontal?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  marginVertical?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  gap?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
  backgroundColor?: string;
  borderRadius?: 'xs' | 'sm' | 'md' | 'lg' | 'full';
  flex?: number;
  flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
  flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse';
  width?: number | string;
  height?: number | string;
  style?: any;
  testID?: string;
}

Example:

<Box padding={'lg'} backgroundColor={theme.colors.surface} borderRadius={'md'}>
  <Text>Content</Text>
</Box>

Row & Column

Flex container components for horizontal and vertical layouts.

// Row = Box with flexDirection='row' and alignItems='center' by default
<Row gap={'md'} padding={'lg'}>
  {/* Horizontal layout */}
</Row>

// Column = Box with flexDirection='column'
<Column gap={'md'} padding={'lg'}>
  {/* Vertical layout */}
</Column>

Both components accept all BoxProps.

Collapsible

Expandable/collapsible section with animated transitions.

interface CollapsibleProps {
  title: string;
  children: React.ReactNode;
  initiallyExpanded?: boolean;
  style?: any;
  testID?: string;
}

Example:

<Collapsible title={'Advanced Settings'} initiallyExpanded={false}>
  <Text>Hidden content that can be toggled</Text>
</Collapsible>

Input Components

Button

Interactive button component with multiple variants and sizes.

interface ButtonProps {
  label: string;
  onPress: () => void;
  variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  style?: any;
  testID?: string;
}

Variants:

• primary - Primary action button (default)
• secondary - Secondary action button
• danger - Destructive action button
• ghost - Transparent button with border

Sizes:

• small - 32px height
• medium - 48px height (default)
• large - 56px height

Example:

<Button
  label={'Submit'}
  onPress={handleSubmit}
  variant={'primary'}
  size={'large'}
  icon={<Icon name="check" />}
/>

Input

Text input component with label and error support.

interface InputProps {
  value: string;
  onChangeText: (text: string) => void;
  placeholder?: string;
  label?: string;
  error?: string;
  editable?: boolean;
  secureTextEntry?: boolean;
  keyboardType?: 'default' | 'numeric' | 'email-address' | 'phone-pad';
  multiline?: boolean;
  numberOfLines?: number;
  style?: any;
  testID?: string;
}

Example:

<Input
  label={'Email'}
  value={email}
  onChangeText={setEmail}
  placeholder={'Enter your email'}
  keyboardType={'email-address'}
  error={emailError}
/>

CheckBox

Checkbox component for boolean selections.

interface CheckBoxProps {
  value: boolean;
  onValueChange: (value: boolean) => void;
  label?: string;
  disabled?: boolean;
  style?: any;
  testID?: string;
}

Example:

<CheckBox
  value={isChecked}
  onValueChange={setIsChecked}
  label={'I agree to the terms'}
/>

RadioButton

Radio button for single selection from a group.

interface RadioButtonProps {
  value: string;
  selected: string;
  onSelect: (value: string) => void;
  label?: string;
  disabled?: boolean;
  style?: any;
  testID?: string;
}

Example:

<Column gap={'sm'}>
  <RadioButton
    value={'option1'}
    selected={selectedOption}
    onSelect={setSelectedOption}
    label={'Option 1'}
  />
  <RadioButton
    value={'option2'}
    selected={selectedOption}
    onSelect={setSelectedOption}
    label={'Option 2'}
  />
</Column>

Switch

Toggle switch for boolean values.

interface SwitchProps {
  value: boolean;
  onValueChange: (value: boolean) => void;
  disabled?: boolean;
  style?: any;
  testID?: string;
}

Example:

<Switch
  value={isEnabled}
  onValueChange={setIsEnabled}
/>

Display Components

ProgressBar

Horizontal progress indicator.

interface ProgressBarProps {
  progress: number; // 0-1 range
  height?: number;
  color?: string;
  backgroundColor?: string;
  borderRadius?: 'xs' | 'sm' | 'md' | 'lg' | 'full';
  style?: any;
  testID?: string;
}

Example:

<ProgressBar
  progress={0.65}
  height={8}
  color={theme.colors.primary}
  borderRadius={'full'}
/>

Badge

Small status badge for labels and notifications.

interface BadgeProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
  size?: 'small' | 'medium' | 'large';
  style?: any;
  testID?: string;
}

Variants:

• primary - Blue badge
• secondary - Gray badge
• success - Green badge
• error - Red badge
• warning - Orange badge
• info - Light blue badge

Example:

<Badge variant={'success'} size={'small'}>
  Active
</Badge>

Divider

Visual separator line (horizontal or vertical).

interface DividerProps {
  orientation?: 'horizontal' | 'vertical';
  thickness?: number;
  color?: string;
  style?: any;
  testID?: string;
}

Example:

<Divider orientation={'horizontal'} thickness={1} />

Typography Components

Text

Base text component with theme-aware typography variants.

interface TextProps {
  children?: React.ReactNode;
  variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 
            'body1' | 'body2' | 'body3' | 'body4' | 'body5' | 'body6' |
            'subtitle1' | 'subtitle2' | 'caption' | 'overline';
  color?: string;
  textAlign?: 'auto' | 'left' | 'right' | 'center' | 'justify';
  style?: any;
  testID?: string;
}

Typography Hierarchy:

• Headings: H1 (48px), H2 (40px), H3 (32px), H4 (28px), H5 (24px), H6 (20px)
• Body: Body1-Body6 (16px-11px)
• Subtitles: SubTitle1 (18px), SubTitle2 (16px)
• Small: Caption (12px), Overline (10px)

Example:

<Column gap={'sm'}>
  <H1>Main Heading</H1>
  <Body1>Regular body text</Body1>
  <Caption>Small caption text</Caption>
  <Text variant={'body2'} color={theme.colors.error}>
    Custom colored text
  </Text>
</Column>

Convenience Components:

All heading and body variants are exported as standalone components:

import { H1, H2, H3, Body1, Body2, SubTitle1, Caption, Overline } from 'react-native-atomic-ui';

// Use directly without variant prop
<H1>Heading</H1>
<Body1>Body text</Body1>
<Caption>Caption</Caption>

🛠️ TypeScript Support

Full TypeScript support with strict mode enabled:

import {
  Box,
  Button,
  Theme,
  ThemeContextValue,
  BoxProps,
  ButtonProps,
} from 'react-native-atomic-ui';

// All components are fully typed
const myComponent: React.FC<BoxProps> = (props) => {
  return <Box {...props} />;
};

📱 Platform Support

| Platform | Min Version | Support | |----------|-------------|---------| | iOS | 12.0 | ✅ Full support | | Android | 6.0 (API 23) | ✅ Full support | | React Native | 0.73.0 | ✅ Full support |

⚙️ Configuration

Theme Provider Options

<ThemeProvider defaultTheme="system">
  {/* 'system' = use device preference (default) */}
  {/* 'light' = force light theme */}
  {/* 'dark' = force dark theme */}
  <App />
</ThemeProvider>

🐛 Troubleshooting

"useTheme must be used within ThemeProvider"

Make sure your app is wrapped with ThemeProvider:

import { ThemeProvider } from 'react-native-atomic-ui';

export function Root() {
  return (
    <ThemeProvider>
      <App />
    </ThemeProvider>
  );
}

TypeScript Errors

Ensure jsx: 'react-native' in your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-native"
  }
}

Font Issues on iOS

If custom fonts aren't loading, ensure they're linked in Info.plist:

<key>UIAppFonts</key>
<array>
  <string>Poppins-Regular.ttf</string>
  <string>Poppins-Medium.ttf</string>
  <string>Poppins-SemiBold.ttf</string>
  <string>Poppins-Bold.ttf</string>
</array>

📄 License

MIT © React Native Atomic UI Team

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📖 Documentation

• Component API
• Setup Guide
• Theming Guide
• Testing Instructions
• Architecture

🔗 Links

• GitHub Repository
• npm Package
• Issue Tracker