expo-dynamic-form

A highly customizable dynamic form component for React Native and Expo applications. This package provides a flexible and powerful way to create dynamic forms with various input types, validation, and multi-step support.

Features

🚀 Multiple controller types:
- Text inputs (text, email, password, number)
- Selection inputs (select, multi-select, searchable-select)
- Date and time inputs (date, date-of-birth, datetime)
- Location inputs (location, multi-location, current-location)
- Special inputs (phone, tags, currency, rich text)
- File and image inputs (file upload, image gallery, featured image)
- Advanced inputs (list creator, sub-form)
📝 Form Capabilities:
- Multi-step form support with dynamic navigation
- Form validation using Zod schemas
- Conditional field rendering
- Dynamic field mapping
- Nested form support
- Integration with react-hook-form
🎨 Customization Options:
- Fully typed with TypeScript
- Customizable UI components

Installation

# Using npm
npm install expo-dynamic-form

# Using yarn
yarn add expo-dynamic-form

Required Peer Dependencies

npm install react-hook-form @hookform/resolvers zod date-fns
npm install @react-native-community/datetimepicker @react-native-async-storage/async-storage
npm install expo-document-picker expo-file-system expo-image-picker expo-location
npm install axios

Basic Usage

Simple Form with API Submission

import React from "react";
import { View, StyleSheet } from "react-native";
import DynamicForm, { initConfig } from "expo-dynamic-form";
import { z } from "zod";

export default function App() {
  // Initialize global API configuration (optional)
  React.useEffect(() => {
    initConfig(
      {
        api: {
          baseURL: "https://your-api-base-url.com",
          headers: {
            "Content-Type": "application/json",
          },
          timeout: 30000,
        },
      },
      async () => {
        // Optional: Custom session token retrieval
        return { accessToken: "your-access-token" };
      }
    );
  }, []);

  // Create a schema for form validation
  const formSchema = z.object({
    name: z.string().min(2, "Name must be at least 2 characters"),
    email: z.string().email("Invalid email address"),
    age: z.number().min(18, "You must be at least 18 years old"),
  });

  // Define your form controllers
  const controllers = [
    {
      name: "name",
      label: "Full Name",
      type: "text",
      placeholder: "Enter your full name",
    },
    {
      name: "email",
      label: "Email Address",
      type: "email",
      placeholder: "Enter your email",
    },
    {
      name: "age",
      label: "Your Age",
      type: "number",
      placeholder: "Enter your age",
    },
  ];

  // API Submission Example
  const apiOptions = {
    api: "/users/create", // Relative API endpoint
    method: "POST",
    options: {
      // Optional axios config
      headers: {
        "X-Custom-Header": "value",
      },
    },
    extraData: {
      // Optional additional data to be sent with form submission
      source: "mobile-app",
    },
    errorHandler: (error, type) => {
      // Custom error handling
      if (type === "FORM_ERROR") {
        console.error("Form submission error:", error);
      }
    },
    onFinish: (data) => {
      // Callback after successful submission
      console.log("Submission completed:", data);
    },
  };

  return (
    <View style={styles.container}>
      <DynamicForm
        controllers={controllers}
        formSchema={formSchema}
        apiOptions={apiOptions}
        submitBtn={{ title: "Submit Form" }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    backgroundColor: "#fff",
  },
});

Key API Submission Features

The DynamicForm component provides powerful API submission capabilities:

Automatic Error Handling: Handles form-level and API-level errors
Flexible API Configuration:
- Specify API endpoint
- Choose HTTP method
- Add custom headers
- Include extra data
Error Callback: Custom error handling
Submission Callback: Handle successful submissions
Global Configuration: Set base URL, default headers via initConfig()

The component uses Axios under the hood, supporting:

Automatic token attachment
Timeout configuration
Custom error handling
Flexible API interaction

Multi-step Form Example

import React from "react";
import { View, StyleSheet } from "react-native";
import DynamicForm from "expo-dynamic-form";
import { z } from "zod";

export default function App() {
  // Create schemas for each step
  const personalInfoSchema = z.object({
    name: z.string().min(2, "Name must be at least 2 characters"),
    email: z.string().email("Invalid email address"),
  });

  const addressSchema = z.object({
    street: z.string().min(5, "Please enter a valid street address"),
    city: z.string().min(2, "City is required"),
    zipCode: z.string().min(5, "ZIP code is required"),
  });

  // Define steps for your form
  const steps = [
    {
      stepName: "Personal Information",
      stepSchema: personalInfoSchema,
      controllers: [
        {
          name: "name",
          label: "Full Name",
          type: "text",
          placeholder: "Enter your full name",
        },
        {
          name: "email",
          label: "Email Address",
          type: "email",
          placeholder: "Enter your email",
        },
      ],
    },
    {
      stepName: "Address",
      stepSchema: addressSchema,
      controllers: [
        {
          name: "street",
          label: "Street Address",
          type: "text",
          placeholder: "Enter street address",
        },
        {
          name: "city",
          label: "City",
          type: "text",
          placeholder: "Enter city",
        },
        {
          name: "zipCode",
          label: "ZIP Code",
          type: "text",
          placeholder: "Enter ZIP code",
        },
      ],
    },
  ];

  // Handle form submission
  const handleSubmit = async ({ values }) => {
    console.log("Form values:", values);
    // Process form data here
  };

  return (
    <View style={styles.container}>
      <DynamicForm
        steps={steps}
        formtype="steper"
        handleSubmit={handleSubmit}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    backgroundColor: "#fff",
  },
});

Controller Types

The package supports a wide range of controller types:

Text Inputs
- text: Standard text input
- email: Email input with validation
- password: Secure text input
- number: Numeric input
- textarea: Multi-line text input
Selection Inputs
- select: Dropdown select
- multi-select: Multi-selection dropdown
- searchable-select: Searchable dropdown
- group-checkbox: Group of checkboxes
Date and Time Inputs
- date: Date picker
- date-of-birth: Specialized date of birth picker
- datetime: Combined date and time picker
Location Inputs
- location: Single location selection
- multi-location: Multiple location selection
- current-location: Current device location
Special Inputs
- phone: Phone number input with country code
- tags-input: Tagging input
- currency: Currency selection
- rich-text: Rich text editor
File and Image Inputs
- file-upload: File upload with multiple type support
- image-gallery: Multiple image upload
- featured-image: Single image upload
Advanced Inputs
- sub-form: Nested form support
- list-creator: Dynamic list creation
- react-node: Custom React component input

API Reference

DynamicForm Props

Prop	Type	Description
`controllers`	`FormControllerProps[]`	Array of form controllers for normal forms
`steps`	`StepsType<ZodSchema>[]`	Array of step configurations for multi-step forms
`formSchema`	`ZodSchema`	Zod schema for form validation
`formtype`	`"normal" \| "steper"`	Type of form to render (default: "normal")
`handleSubmit`	`(params: DynamicFormHanldeSubmitParamType<ZodSchema>) => Promise<void>`	Function to handle form submission
`submitBtn`	`{ title?: string }`	Configuration for submit button
`stepPreview`	`(value: any) => ReactNode`	Function to render step preview in multi-step forms
`hideStepsIndication`	`boolean`	Hide step indicators in multi-step forms
`apiOptions`	`apiOptionsType`	API configuration for form submission
`tricker`	`(props: any) => ReactNode`	Custom trigger for form submission
`props`	`PropsPropsType`	Custom props for form components
`modalComponent`	`(data: ModalType, setModal: (modal: ModalType) => void) => ReactNode`	Custom modal component

Configuration

Global API Configuration

You can initialize global configuration for API calls using the initConfig method:

import { initConfig } from "expo-dynamic-form";
import config from "./form.config.json";
import { getSession } from "./your-session-service";

// Optional: Pass a configuration object and a session retrieval function
initConfig(config, getSession);

Configuration Object Example

Create a form.config.json in your project root:

{
  "api": {
    "baseURL": "https://your-api-base-url.com",
    "headers": {
      "Content-Type": "application/json"
    },
    "timeout": 30000
  }
}

Session Retrieval Function

The session retrieval function is optional and can be used to dynamically fetch access tokens:

// Example session service
export const getSession = async () => {
  try {
    // Retrieve stored session data
    const storedSession = await AsyncStorage.getItem("user_session");

    if (storedSession) {
      const sessionData = JSON.parse(storedSession);
      return {
        accessToken: sessionData.accessToken,
      };
    }

    return { accessToken: undefined };
  } catch (error) {
    console.error("Failed to retrieve session", error);
    return { accessToken: undefined };
  }
};

Advanced API Submission Options

apiOptions={{
  api: "/auth/login",
  method: "POST",
  options: {
    // Optional Axios configuration
    headers: {
      'X-Custom-Header': 'value'
    },
    // Additional Axios request configuration
    withCredentials: true
  },
  extraData: {
    // Additional data to be sent with the request
    deviceInfo: 'mobile-app',
    timezone: 'UTC'
  },
  onVerify: (data) => {
    // Handle verification steps (e.g., two-factor authentication)
    if (data.requiresVerification) {
      // Trigger additional verification process
      navigateToVerificationScreen();
    }
  },
  onFinish: async (data) => {
    // Handle successful submission
    await saveUserSession(data);
    navigateToMainScreen();
  }
}}

Error Handling and Form Validation

The package provides a sophisticated error handling mechanism that seamlessly integrates backend validation with Zod schema validation.

Backend Error Response Format

Your backend can return errors in two primary formats:

Single Error Object:

{
  "error": {
    "path": ["email"],
    "message": "Invalid Email Or Password"
  },
  "errorType": "FORM_ERROR"
}

Multiple Errors Array:

{
  "errors": [
    {
      "path": ["email"],
      "message": "Invalid Email address"
    },
    {
      "path": ["password"],
      "message": "Password is too short"
    }
  ],
  "errorType": "FORM_ERROR"
}

How Error Handling Works

Automatic Error Mapping: The form automatically maps backend errors to specific form fields
Supports Single and Multiple Errors: Works with both single error objects and error arrays
Zod Schema Compatibility: Error structure matches Zod's safeParse error format
Field-Specific Error Placement: Errors are displayed next to corresponding form fields

Example Backend Error Handling:

// Express.js example
app.post("/auth/login", (req, res) => {
  // Authentication logic
  if (!isValidUser) {
    return res.status(404).json({
      error: {
        path: ["email"],
        message: "Invalid Email Or Password",
      },
      errorType: "FORM_ERROR",
    });
  }

  // Multiple errors example
  if (validationFailed) {
    return res.status(400).json({
      errors: [
        {
          path: ["email"],
          message: "Email is required",
        },
        {
          path: ["password"],
          message: "Password must be at least 8 characters",
        },
      ],
      errorType: "FORM_ERROR",
    });
  }
});

Verification Flow

The package supports advanced verification scenarios, such as two-factor authentication or email verification:

{
  "succesType": "VERIFIED",
  "data": {
    "user": { ... },
    "requiresAdditionalAction": true
  }
}

Example API Options for Verification:

apiOptions={{
  api: "/auth/login",
  method: "POST",
  onVerify: (data) => {
    // Handle verification steps
    if (data.requiresVerification) {
      // Trigger additional verification process
      navigateToVerificationScreen();
    }
  },
  onFinish: async (data) => {
    // Handle final successful authentication
    if (data.succesType === "VERIFIED") {
      await saveUserSession(data.data);
      navigateToMainScreen();
    }
  }
}}

Verification Flow Characteristics

Flexible Verification Handling:
- Detect when additional verification is needed
- Support for multi-step authentication processes
Success Types:
- VERIFIED: Indicates complete authentication
- Allows for conditional navigation based on verification status
Rich Metadata:
- Carry additional user or verification-related data
- Support complex authentication scenarios

Backend Example:

app.post("/auth/login", (req, res) => {
  // Authentication logic
  if (needsTwoFactorVerification) {
    return res.status(200).json({
      succesType: "VERIFIED",
      data: {
        user: partialUserData,
        requiresVerification: true,
        verificationMethod: "otp",
      },
    });
  }

  // Complete authentication
  if (authenticationSuccessful) {
    return res.status(200).json({
      succesType: "VERIFIED",
      data: {
        user: fullUserData,
        accessToken: generatedToken,
      },
    });
  }
});

Key Configuration Features

Flexible Configuration:
- Global API settings via JSON config
- Optional session token retrieval
- Dynamic headers and timeout
Seamless Token Management:
- Automatically attach access tokens
- Support for custom session retrieval
Error Handling:
- Built-in error management
- Custom error callback support
Submission Callbacks:
- onFinish for successful submissions
- errorHandler for custom error processing

The configuration is designed to be:

Optional
Easily customizable
Adaptable to different project structures

Contributing

Contributions are welcome! Please see the contributing guide for details on how to get started.

License

MIT License