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>

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github		.github
.vscode		.vscode
__mocks__		__mocks__
examples		examples
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
TESTING.md		TESTING.md
TESTING_INSTRUCTIONS.md		TESTING_INSTRUCTIONS.md
babel.config.js		babel.config.js
esbuild.config.js		esbuild.config.js
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

react-native-atomic-ui

✨ Features

📦 Core Components (Zero Dependencies)

Layout Components

Typography Components

Input Components

Display Components

🚀 Installation

Basic Setup

iOS Additional Setup

📱 Example App

🔧 Quick Start

1. Install the Package

2. Setup Theme Provider

3. Start Using Components

🎨 Theme & Customization

Light/Dark Modes

Accessing Theme Colors

Spacing System

Typography

📚 Component API Reference

Layout Components

Box

Row & Column

Collapsible

Input Components

Button

Input

CheckBox

RadioButton

Switch

Display Components

ProgressBar

Badge

Divider

Typography Components

Text

🛠️ TypeScript Support

📱 Platform Support

⚙️ Configuration

Theme Provider Options

🐛 Troubleshooting

"useTheme must be used within ThemeProvider"

TypeScript Errors

Font Issues on iOS

📄 License

🤝 Contributing

📖 Documentation

🔗 Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages