Overview
This guide helps you migrate from popular React Native UI libraries to Docyrus UI Native. Each section covers the key differences and provides mapping tables for common components.
From React Native Paper
React Native Paper uses Material Design. Docyrus UI Native follows a custom design system with semantic color tokens.
Theme Migration
// Before (Paper)
import { Provider as PaperProvider, DefaultTheme } from 'react-native-paper';
const theme = {
...DefaultTheme,
colors: {
...DefaultTheme.colors,
primary: '#6200ee',
accent: '#03dac4',
},
};
<PaperProvider theme={theme}>
<App />
</PaperProvider>
// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';
<DocyThemeProvider colorScheme="violet" mode="system">
<App />
</DocyThemeProvider>Component Mapping
| Paper | Docyrus UI Native | Notes |
|---|---|---|
<Button> | <Button> | Use variant prop instead of mode |
<TextInput> | <Input> | Different prop names |
<Card> | <Card> | Similar structure |
<Chip> | <Badge> | Different naming |
<Dialog> | <Modal> | Uses visible prop |
<Snackbar> | <Toast> | Different API |
<DataTable> | <DataTable> | Richer API with sorting, filtering |
<FAB> | No direct equivalent | Build with <Button> + absolute positioning |
<BottomNavigation> | Use Expo Router tabs | Framework-level navigation |
Styling Differences
// Paper — theme.colors.primary
const { colors } = useTheme();
<View style={{ backgroundColor: colors.primary }}>
// Docyrus — useDocyTheme().colors.primary
const { colors } = useDocyTheme();
<View style={{ backgroundColor: colors.primary }}>From NativeBase
NativeBase uses a utility-first styling approach similar to Tailwind. Docyrus UI Native uses direct style objects.
Theme Migration
// Before (NativeBase)
import { NativeBaseProvider, extendTheme } from 'native-base';
const theme = extendTheme({
colors: { primary: { 500: '#6200ee' } },
});
<NativeBaseProvider theme={theme}>
<App />
</NativeBaseProvider>
// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';
<DocyThemeProvider colorScheme="violet" mode="system">
<App />
</DocyThemeProvider>Styling Differences
// NativeBase — utility props
<Box bg="primary.500" p={4} rounded="lg" shadow={2}>
<Text color="white" fontSize="lg">Hello</Text>
</Box>
// Docyrus — style objects with theme
const { colors, spacing, borderRadius } = useDocyTheme();
<View style={{
backgroundColor: colors.primary,
padding: spacing[4],
borderRadius: borderRadius.lg,
elevation: 2,
}}>
<Text style={{ color: colors.primaryForeground, fontSize: 18 }}>Hello</Text>
</View>Component Mapping
| NativeBase | Docyrus UI Native | Notes |
|---|---|---|
<Box> | <View> | Use React Native's View |
<Button> | <Button> | Similar API |
<Input> | <Input> | Similar API |
<Select> | <Select> | Different styling |
<Modal> | <Modal> | Similar API |
<Toast> | <Toast> | Different API |
<Avatar> | <Avatar> | Similar API |
<Badge> | <Badge> | Similar API |
<Spinner> | <ActivityIndicator> | Use React Native's |
From Tamagui
Tamagui uses a compiler-optimized styling system. Docyrus UI Native uses runtime styling via theme context.
Key Differences
| Feature | Tamagui | Docyrus UI Native |
|---|---|---|
| Styling | Compiled (build-time) | Runtime (theme context) |
| Tokens | $size.4, $color.blue | spacing[4], colors.blue[500] |
| Animations | @tamagui/animations-react-native | Direct Animated or reanimated |
| Web support | Universal (web + native) | Native only |
| Theme system | Token-based with createTheme | Semantic color schemes |
Styling Migration
// Tamagui — token-based props
<YStack padding="$4" backgroundColor="$background" borderRadius="$4">
<Text color="$color" fontSize="$5">Hello</Text>
</YStack>
// Docyrus — style objects
const { colors, spacing, borderRadius } = useDocyTheme();
<View style={{
padding: spacing[4],
backgroundColor: colors.background,
borderRadius: borderRadius.lg,
}}>
<Text style={{ color: colors.foreground, fontSize: 18 }}>Hello</Text>
</View>From Gluestack UI
Gluestack UI is the spiritual successor to NativeBase with a new styling engine.
Key Differences
| Feature | Gluestack | Docyrus UI Native |
|---|---|---|
| Styling | styled() + utility props | useDocyTheme() + style objects |
| Tokens | Design tokens via config | Semantic colors + spacing scale |
| Components | Headless + styled | Styled with theme |
Migration Pattern
// Gluestack
import { Button, ButtonText } from '@gluestack-ui/themed';
<Button size="md" variant="solid" action="primary">
<ButtonText>Click me</ButtonText>
</Button>
// Docyrus
import { Button } from '@/components/docyrus-native/button';
<Button variant="default" size="default" onPress={handlePress}>
Click me
</Button>General Migration Tips
1. Install DocyThemeProvider First
Before migrating any components, set up the theme provider at your app root. This ensures all migrated components have access to theme values.
2. Migrate Bottom-Up
Start with leaf components (Button, Input, Badge) and work up to compound components (DataTable, Form). This minimizes cascading changes.
3. Keep Both Libraries Temporarily
During migration, you can use both libraries simultaneously. Remove the old library only after all components are migrated.
{
"dependencies": {
"react-native-paper": "^5.0.0",
"@docyrus/ui-native": "workspace:*"
}
}4. Map Your Color Tokens
Create a mapping between your current library's color tokens and Docyrus semantic tokens:
| Your Token | Docyrus Token |
|---|---|
primary | colors.primary |
onPrimary | colors.primaryForeground |
surface | colors.card |
onSurface | colors.cardForeground |
error | colors.destructive |
background | colors.background |
5. Replace Theme Hooks
Find-and-replace your current theme hook with Docyrus:
// Common patterns to replace
useTheme() → useDocyTheme()
theme.colors.X → colors.X
theme.spacing.X → spacing[X]
theme.roundness → borderRadius.DEFAULT6. Update Imports
After installing Docyrus components via CLI:
docyrus add rn-button rn-input rn-card rn-badgeUpdate imports:
// Before
import { Button } from 'react-native-paper';
// After
import { Button } from '@/components/docyrus-native/button';