Zero-dependency atomic UI components library for React Native with built-in dark mode support
npm install react-native-atomic-uiA zero-dependency atomic UI component library for React Native with built-in dark mode support.
- ✅ 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 (Redux optional for advanced use cases)
- ✅ Small Bundle - ~50-80 KB minified core library
- ✅ Modular Architecture - Import only what you need
- ✅ Advanced Components - Optional peer dependencies for date pickers, rich text, file selection
- ✅ Platform Support - iOS 12.0+, Android 6.0+
- ✅ React Native 0.73.0+ - Broad ecosystem compatibility
Box - Flexible container with theme-aware spacingRow - Horizontal flex containerColumn - Vertical flex containerCollapsible - Expandable/collapsible sectionsText - Base text component with theme variantsH1, H2, H3, H4, H5, H6 - Heading levelsBody1 - Body6 - Body text variantsSubTitle1, SubTitle2 - Subtitle componentsCaption, Overline - Small text variantsButton - Multi-variant buttons (primary, secondary, danger, ghost)Input - Text input with theme supportFloatingInput - Floating label text inputBorderedInput - Bordered text input variantInputNumber - Numeric input with validationRadioButton / RadioGroup - Radio selectionCheckBox - Checkbox componentCheckBoxMultiPicker - Multi-select checkboxesScaledImage - Responsive image containerPaginatedFlatList - Lazy-loaded list with paginationPasswordReport - Password strength indicatorShowMoreText - Expandable text displayHorizontalProgressBar - Progress bar component``bash`
npm install react-native-atomic-uior
yarn add react-native-atomic-ui
Note: react and react-native are peer dependencies and should already be installed in your React Native project.
After installation, if you're on iOS, install pods:
`bash`
cd ios && pod install && cd ..
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:
`bash`
cd examples/app
npm install
cd ios && pod install && cd ..
npx react-native run-ios # or run-android
`bashFor date picker
npm install @react-native-community/datetimepicker
🔧 Quick Start
$3
`bash
npm install react-native-atomic-ui
`$3
Wrap your app with
ThemeProvider at the root level (usually in index.js or App.tsx):`typescript
import React from 'react';
import { ThemeProvider } from 'react-native-atomic-ui';
import { App } from './App';export function Root() {
return (
);
}
`$3
`typescript
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 (
Welcome to Atomic UI
This is a beautiful, themeable UI library.
label={isDark ? '☀️ Light Mode' : '🌙 Dark Mode'}
onPress={toggleTheme}
variant="primary"
size="large"
/>
);
}
`🎨 Theme & Customization
$3
The library automatically detects system color scheme and provides both light and dark themes:
`typescript
import { useTheme } from 'react-native-atomic-ui';export function ThemedComponent() {
const { theme, isDark, toggleTheme } = useTheme();
return (
{/ Your content /}
label="Toggle Theme"
onPress={toggleTheme}
/>
);
}
`$3
`typescript
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...
`$3
The theme includes a consistent spacing scale:
`typescript
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
`$3
Use named variants for consistent typography:
`typescript
import { H1, Body1, Caption, Text, useTheme } from 'react-native-atomic-ui';export function TypographyExample() {
const { theme } = useTheme();
return (
Heading 1 - 48px
Body text - 16px
Caption - 12px
Custom variant
variant="body2"
color={theme.colors.textSecondary}
>
Custom color
);
}
`📚 Component API Reference
$3
#### Box
Flexible container component for layout with theme-aware spacing.
`typescript
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:
`typescript
Content
`#### Row & Column
Flex container components for horizontal and vertical layouts.
`typescript
// Row = Box with flexDirection='row' and alignItems='center' by default
{/ Horizontal layout /}
|
// Column = Box with flexDirection='column'
{/ Vertical layout /}
`Both components accept all
BoxProps.#### Collapsible
Expandable/collapsible section with animated transitions.
`typescript
interface CollapsibleProps {
title: string;
children: React.ReactNode;
initiallyExpanded?: boolean;
style?: any;
testID?: string;
}
`Example:
`typescript
Hidden content that can be toggled
`---
$3
#### Button
Interactive button component with multiple variants and sizes.
`typescript
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 borderSizes:
-
small - 32px height
- medium - 48px height (default)
- large - 56px heightExample:
`typescript
label={'Submit'}
onPress={handleSubmit}
variant={'primary'}
size={'large'}
icon={ }
/>
`#### Input
Text input component with label and error support.
`typescript
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:
`typescript
label={'Email'}
value={email}
onChangeText={setEmail}
placeholder={'Enter your email'}
keyboardType={'email-address'}
error={emailError}
/>
`#### CheckBox
Checkbox component for boolean selections.
`typescript
interface CheckBoxProps {
value: boolean;
onValueChange: (value: boolean) => void;
label?: string;
disabled?: boolean;
style?: any;
testID?: string;
}
`Example:
`typescript
value={isChecked}
onValueChange={setIsChecked}
label={'I agree to the terms'}
/>
`#### RadioButton
Radio button for single selection from a group.
`typescript
interface RadioButtonProps {
value: string;
selected: string;
onSelect: (value: string) => void;
label?: string;
disabled?: boolean;
style?: any;
testID?: string;
}
`Example:
`typescript
value={'option1'}
selected={selectedOption}
onSelect={setSelectedOption}
label={'Option 1'}
/>
value={'option2'}
selected={selectedOption}
onSelect={setSelectedOption}
label={'Option 2'}
/>
`#### Switch
Toggle switch for boolean values.
`typescript
interface SwitchProps {
value: boolean;
onValueChange: (value: boolean) => void;
disabled?: boolean;
style?: any;
testID?: string;
}
`Example:
`typescript
value={isEnabled}
onValueChange={setIsEnabled}
/>
`---
$3
#### ProgressBar
Horizontal progress indicator.
`typescript
interface ProgressBarProps {
progress: number; // 0-1 range
height?: number;
color?: string;
backgroundColor?: string;
borderRadius?: 'xs' | 'sm' | 'md' | 'lg' | 'full';
style?: any;
testID?: string;
}
`Example:
`typescript
progress={0.65}
height={8}
color={theme.colors.primary}
borderRadius={'full'}
/>
`#### Badge
Small status badge for labels and notifications.
`typescript
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 badgeExample:
`typescript
Active
`#### Divider
Visual separator line (horizontal or vertical).
`typescript
interface DividerProps {
orientation?: 'horizontal' | 'vertical';
thickness?: number;
color?: string;
style?: any;
testID?: string;
}
`Example:
`typescript
`---
$3
#### Text
Base text component with theme-aware typography variants.
`typescript
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:
`typescript
Main Heading
Regular body text
Small caption text
Custom colored text
`Convenience Components:
All heading and body variants are exported as standalone components:
`typescript
import { H1, H2, H3, Body1, Body2, SubTitle1, Caption, Overline } from 'react-native-atomic-ui';// Use directly without variant prop
Heading
Body text
Caption
`🔗 Advanced Components
Advanced components require specific peer dependencies. Import them from submodules:
$3
`typescript
import { DatePickerInput } from 'react-native-atomic-ui/date-picker';// Requires: npm install @react-native-community/datetimepicker
value={date}
onChange={setDate}
label="Select Date"
format="DD/MM/YYYY"
/>
`$3
`typescript
import { BorderedPickerInput } from 'react-native-atomic-ui/picker';// Requires: npm install react-native-picker-select
value={selectedValue}
onValueChange={setSelectedValue}
items={[
{ label: 'Option 1', value: '1' },
{ label: 'Option 2', value: '2' },
]}
label="Select an option"
/>
`$3
`typescript
import { FilePicker } from 'react-native-atomic-ui/file-picker';// Requires: npm install @react-native-documents/picker
onFileSelected={handleFileSelected}
label="Choose File"
/>
`$3
`typescript
import { RichText, RichTextInput } from 'react-native-atomic-ui/rich-text';// Requires: npm install react-native-webview
// For editor: npm install github:starburst997/10tap-editor#jd
html="
This is rich text
"
onLinkPress={(url) => Linking.openURL(url)}
/>
`🛠️ TypeScript Support
Full TypeScript support with strict mode enabled:
`typescript
import {
Box,
Button,
Theme,
ThemeContextValue,
BoxProps,
ButtonProps,
} from 'react-native-atomic-ui';// All components are fully typed
const myComponent: React.FC = (props) => {
return ;
};
`📱 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
$3
`typescript
{/ 'system' = use device preference (default) /}
{/ 'light' = force light theme /}
{/ 'dark' = force dark theme /}
`🐛 Troubleshooting
$3
Make sure your app is wrapped with
ThemeProvider:`typescript
import { ThemeProvider } from 'react-native-atomic-ui';export function Root() {
return (
);
}
`$3
Ensure
jsx: 'react-native' in your tsconfig.json:`json
{
"compilerOptions": {
"jsx": "react-native"
}
}
`$3
If custom fonts aren't loading, ensure they're linked in Info.plist:
`xml
UIAppFonts
Poppins-Regular.ttf
Poppins-Medium.ttf
Poppins-SemiBold.ttf
Poppins-Bold.ttf
``MIT © React Native Atomic UI Team
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Component API
- Setup Guide
- Theming Guide
- Testing Instructions
- Architecture