Dynamic Home - React Native JSON UI Engine

A powerful, highly extensible, standalone JSON-to-React-Native-UI rendering engine. Build entire React Native screens or embeddable components dynamically directly from JSON configuration.

Perfect for Server-Driven UI (SDUI), live A/B testing, no-code/low-code builders, and delivering dynamic content without pushing app updates.

🌟 Cross-Platform Ecosystem: This package is part of the Dynamic Home ecosystem. We provide identical packages for both React Native (react-native-json-dynamic-home) and Flutter (flutter_json_dynamic_home). You design your UI once, and the exact same JSON powers both platforms!

🎨 Dynamic Home Screen Editor (Online Builder)

You don't need to write JSON by hand! We provide an advanced Online Visual Editor that allows you to drag, drop, and configure your app's UI visually, providing a live preview and instantly generating a JSON URL for your app.

👉 Try the Dynamic Home Screen Editor: https://pagekart.in

🔥 Advanced Screen Editor Features

• Visual Drag & Drop Interface: Easily add text, images, buttons, and layouts without touching code.
• Real-Time Live Preview: See exactly how your screen will look as you build it.
• Project & Multi-Screen Management: Group multiple screens under a single "App" project. Define a home screen and set up navigation.
• Version Control & API Publishing: Safely draft changes and hit "Publish" to deploy a new API version. Roll back to older versions seamlessly.
• Direct JSON URL Generation: Get a secure, highly-available JSON URL via Supabase Storage directly from the editor.
• App Marketplace: Publish your beautiful UI templates to the public marketplace and allow others to like, clone, and use them!
• Component Styling & Action Mapping: Complete control over padding, margins, colors, and typography, plus map UI buttons to native app actions seamlessly.

Workflow:

1. Design your screen visually at https://pagekart.in.
2. Hit publish to create a new API Version.
3. Copy the URL and pass it to the Dynamic Home package in your React Native app.
4. Your UI updates instantly without submitting a new app store update!

📱 Companion Live Tester App (Dynamic Home App)

Want to see how your design looks on a real device before writing any integration code? We have a Live Tester App built with our Flutter implementation!

• Live Preview on Device: Paste the URL generated by the Screen Editor into the app and see the UI rendered instantly on your physical phone with pixel-perfect native rendering.
• Cross-Platform Building: The source code for this test app is fully open-source. You can download it and build it for both iOS and Android.

👉 Download/Clone the Source Code: Check my GitHub profile for the dynamic_home_app repository to get started with the live tester!

✨ Advanced Package Features

• 100% Decoupled Architecture: No hardcoded app dependencies. Uses React Native's useColorScheme() to adapt to Light/Dark modes instantly.
• Advanced Caching Engine: Built-in JsonLoaderService handles network requests and local caching via AsyncStorage to support offline capabilities.
• Native Action Registry: Trigger native JavaScript/TypeScript code (like purchases, dialogs, analytics) directly from JSON clicks.
• Conditional Routing: Support premium vs free user flows by pointing different user cohorts to different JSON configurations.
• Flexible Embedding: Use DynamicScreen to render full, standalone pages, or DynamicWidgetArea to inject a small JSON snippet directly into an existing React Native view.
• Built-in Pull-to-Refresh: Users can automatically refresh dynamic screens just by pulling down.

🚀 Installation

1. Install the package

# As a git or local dependency
npm install https://github.com/sachi96ff/react-native-json-dynamic-home.git

2. Install peer dependencies

npm install @react-native-async-storage/async-storage
# Optional (for icons):
npm install lucide-react-native react-native-svg

🛠️ Advanced Usage & Example Codes

1. Global Setup with Caching & Headers

Configure the global network behavior in your app entry. You only need to do this once.

import { JsonLoaderService } from 'react-native-json-dynamic-home';
import AsyncStorage from '@react-native-async-storage/async-storage';

// Set AsyncStorage for persistent caching (Optional but recommended)
JsonLoaderService.asyncStorage = AsyncStorage;

// Option A: Set a base URL if you host your own JSON files on your server
// JsonLoaderService.defaultBaseUrl = 'https://api.yourdomain.com/dynamic_ui';

// Option B: Pass full URLs generated by the Screen Editor directly to the screens!

// (Optional) Pass API keys or Auth Tokens if your endpoint is secured
JsonLoaderService.defaultHeaders = {
  'Authorization': 'Bearer YOUR_TOKEN_HERE',
  'x-app-version': '1.0.0'
};

2. Initialize the Engine with Analytics & Custom Actions

Track every click and screen view dynamically, and link JSON buttons to native code!

import { JsonWidgetEngine, JsonAnalyticsDelegate } from 'react-native-json-dynamic-home';
import { Alert } from 'react-native';

const myAnalytics: JsonAnalyticsDelegate = {
  logEvent: (eventName, parameters) => {
    console.log(`Analytics Event -> ${eventName}:`, parameters);
  },
  logScreenView: (screenName) => {
    console.log(`Screen View -> ${screenName}`);
  },
};

const engine = new JsonWidgetEngine({
  analyticsDelegate: myAnalytics,
});

// Register Native Actions so the JSON can trigger them!
engine.actionRegistry.register('purchase_premium', (params) => {
  const plan = params.plan_id;
  console.log(`Trigger Native Purchase Flow for: ${plan}`);
});

engine.actionRegistry.register('show_toast', (params) => {
  Alert.alert('Action triggered!', params.message ?? '');
});

// Configure Navigation for 'navigate' JSON actions
engine.setNavigationRef({
  navigate: (screen, params) => navigation.navigate(screen, params),
  goBack: () => navigation.goBack(),
});

Trigger it from JSON:

{
  "type": "Button",
  "properties": {
    "text": "Buy Premium Now",
    "on_click": {
      "action": "purchase_premium",
      "params": {
        "plan_id": "premium_monthly_99"
      }
    }
  }
}

3. Displaying Full Pages (DynamicScreen)

Use this when your JSON file represents an entire page (like a Settings page, Profile view, or Onboarding screen).

import { DynamicScreen } from 'react-native-json-dynamic-home';
import { ActivityIndicator, View, Text, Button } from 'react-native';

// In your navigation component:
<DynamicScreen
  // Pass the URL generated by the Dynamic Home Screen Editor
  jsonFile="https://pagekart.in/api/screens/custom_onboarding.json"
  engine={engine}
  onBack={() => navigation.goBack()}
  
  // Advanced: Custom Loading state
  loadingComponent={
    <View style={{ flex: 1, justifyContent: 'center' }}>
      <ActivityIndicator size="large" color="purple" />
    </View>
  }
  
  // Advanced: Custom Error state
  errorBuilder={(error, onRetry) => (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Connection Failed</Text>
      <Button title="Retry" onPress={onRetry} />
    </View>
  )}
/>

4. Embedding Components Inline (DynamicWidgetArea)

Perfect for promotional banners inside a statically built feed!

import { DynamicWidgetArea } from 'react-native-json-dynamic-home';
import { ScrollView, Text } from 'react-native';

const HomeScreen = () => (
  <ScrollView>
    <Text>Static React Native Item 1</Text>
    <Text>Static React Native Item 2</Text>
    
    {/* Inject dynamic JSON UI seamlessly directly into a normal screen */}
    <DynamicWidgetArea 
       jsonFile="https://pagekart.in/api/screens/summer_promo_banner.json" 
    />
    
    <Text>Static React Native Item 3</Text>
  </ScrollView>
);

5. Dynamic A/B Testing & User Routing

Control which JSON URL to load based on the user's local state without leaking logic to the UI.

function determineScreenLayout(user) {
  // Free vs Premium experience
  if (user.isPremium) {
    return 'https://pagekart.in/api/screens/dashboard_premium.json';
  } else {
    return 'https://pagekart.in/api/screens/dashboard_free.json';
  }
}

// Push to dynamic screen
<DynamicScreen
  jsonFile={determineScreenLayout(currentUser)}
  engine={engine}
/>

6. Universal Screen Navigation (navigate)

{
  "type": "Button",
  "properties": {
    "text": "Open Details Page",
    "on_click": {
      "action": "navigate",
      "json_file": "https://pagekart.in/api/screens/details.json",
      "params": {
        "title": "Details Page"
      }
    }
  }
}

For navigation to work, you MUST set the navigation ref on the engine (as shown in Step 2).

🏗️ Supported Widgets

The engine supports a robust set of standard widgets matching the Editor:

Content Widgets:

• Title (or H1, Heading)
• Subtitle (or H2)
• Text (or Paragraph)
• Image (or NetworkImage)
• Banner
• Icon
• Divider
• ProgressBar ⭐ NEW — Linear progress indicator
• Badge ⭐ NEW — Notification count badge or status dot
• Avatar ⭐ NEW — Circular user image with fallback initials

Interactive Widgets:

• Button
• IconButton
• Card (or DynamicCard)
• Chip ⭐ NEW — Small rounded label/tag
• TextInput ⭐ NEW — Text field with label, placeholder, hint
• Switch ⭐ NEW — Toggle switch with label and subtitle

Layout & Spacing Widgets:

• Column
• Row
• Container
• Padding
• SizedBox (or Spacer)
• Expanded
• Center
• Grid
• List
• HorizontalList
• Stack ⭐ NEW — Overlapping layout (absolute positioning)
• Wrap ⭐ NEW — Flow layout for tags, chips, badges

🖼️ Screen-Level Configuration

The DynamicScreenConfig supports these screen-level settings:

Background Image Options

| Property | Values | Description | |----------|--------|-------------| | background_image | URL string | Background image URL | | background_fit | cover, contain, fill, none | How the image fits the screen | | background_repeat | no-repeat, repeat, repeat-x, repeat-y | Image repeat behavior | | background_position | center, top, bottom, left, right, top left, etc. | Image alignment | | background_attachment | fixed, scroll | Fixed or scrolling background |

Advanced Screen Options

| Property | Values | Description | |----------|--------|-------------| | safe_area | true / false | Respects iPhone notch / Android status bar | | status_bar_style | light, dark, auto | Status bar icon color | | transition | slide, fade, scale, none | Screen transition animation | | pull_to_refresh | true / false | Enable pull-down refresh gesture | | min_height | "100%" or number | Minimum screen height |

Floating Action Button (FAB)

{
  "fab": {
    "icon": "plus",
    "background": "#6366F1",
    "on_click": {
      "action": "navigate",
      "json_file": "https://example.com/create.json"
    }
  }
}

🎨 JSON Schema Example

Here is an example of a fully structured JSON screen config generated by our editor:

{
  "screen_id": "home_screen",
  "version": "1.0.0",
  "title": "My Dynamic Page",
  "scrollable": true,
  "background": "#F5F5F5",
  "background_image": "https://example.com/bg.png",
  "background_fit": "cover",
  "background_position": "center",
  "safe_area": true,
  "status_bar_style": "auto",
  "pull_to_refresh": true,
  "widgets": [
    {
      "type": "Title",
      "properties": {
        "text": "Welcome Back!"
      },
      "style": {
        "margin": { "left": 16, "top": 16, "right": 16, "bottom": 8 }
      }
    },
    {
      "type": "ProgressBar",
      "properties": {
        "value": 0.75,
        "label": "Profile Complete: 75%",
        "bar_color": "#6366F1"
      }
    },
    {
      "type": "Wrap",
      "properties": { "spacing": 8 },
      "children": [
        { "type": "Chip", "properties": { "text": "Flutter" } },
        { "type": "Chip", "properties": { "text": "React Native" } },
        { "type": "Chip", "properties": { "text": "Dynamic UI", "variant": "outlined" } }
      ]
    },
    {
      "type": "Card",
      "children": [
        {
          "type": "Row",
          "properties": { "spacing": 12 },
          "children": [
            { "type": "Avatar", "properties": { "text": "SK", "size": 40 } },
            { "type": "Text", "properties": { "text": "Sachin Kumar" } }
          ]
        },
        {
          "type": "Switch",
          "properties": { "label": "Notifications", "subtitle": "Receive push alerts", "value": true }
        },
        {
          "type": "Button",
          "properties": {
            "text": "Learn More",
            "on_click": {
              "action": "open_url",
              "url": "https://example.com"
            }
          },
          "style": {
            "margin": { "top": 16 }
          }
        }
      ],
      "style": {
        "margin": { "left": 16, "top": 0, "right": 16, "bottom": 16 },
        "padding": 16,
        "radius": 12,
        "background": "#FFFFFF",
        "elevation": 2
      }
    }
  ]
}

Styling Overview

The style object supports standard styling properties:

• margin and padding (number for uniform, or object { top, bottom, left, right } or { vertical, horizontal })
• background (hex color like "#FF0000")
• textColor / text_color (for text/icons)
• radius (border radius number)
• width / height (number or "auto" or "50%")
• alignment ("center", "topLeft", etc.)
• elevation / shadow (number / boolean)

🔄 Same JSON for Flutter & React Native

This package is designed to be a 1:1 React Native equivalent of the Flutter flutter_json_dynamic_home package. Both packages:

• Parse the exact same JSON schema generated by https://pagekart.in
• Support the same widget types (including all 8 new widgets)
• Handle the same action types (navigate, open_url, custom actions)
• Use the same styling system
• Provide the same caching strategy
• Support identical screen-level config (background image options, safe area, status bar, FAB, etc.)

Your backend (or online editor) can serve one JSON file that works flawlessly on both Flutter and React Native apps!

Built with ❤️. Give your apps the power of dynamic content delivery.