# Native Migration
URL: /docs/guide/native-migration

How to migrate from other React Native UI libraries to Docyrus UI Native.

## 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](https://callstack.github.io/react-native-paper/) uses Material Design. Docyrus UI Native follows a custom design system with semantic color tokens.

### Theme Migration

```tsx
// Before (Paper)
import { Provider as PaperProvider, DefaultTheme } from 'react-native-paper';

const theme = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    primary: '#6200ee',
    accent: '#03dac4',
  },
};

// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';

```

### Component Mapping

| Paper | Docyrus UI Native | Notes |
|-------|-------------------|-------|
| `

// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';

```

### Styling Differences

```tsx
// NativeBase — utility props

// Docyrus — style objects with theme
const { colors, spacing, borderRadius } = useDocyTheme();

```

### Component Mapping

| NativeBase | Docyrus UI Native | Notes |
|------------|-------------------|-------|
| `

// Docyrus — style objects
const { colors, spacing, borderRadius } = useDocyTheme();

```

## From Gluestack UI

[Gluestack UI](https://gluestack.io/) 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

```tsx
// Gluestack
import { Button, ButtonText } from '@gluestack-ui/themed';

// Docyrus
import { Button } from '@/components/docyrus-native/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.

```json
{
  "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:

```tsx
// Common patterns to replace
useTheme()        → useDocyTheme()
theme.colors.X    → colors.X
theme.spacing.X   → spacing[X]
theme.roundness   → borderRadius.DEFAULT
```

### 6. Update Imports

After installing Docyrus components via CLI:

```bash
docyrus add rn-button rn-input rn-card rn-badge
```

Update imports:

```tsx
// Before
import { Button } from 'react-native-paper';

// After
import { Button } from '@/components/docyrus-native/button';
```