Form Component

Overview

The Form component is a powerful, declarative form builder that handles various input types including text fields, document uploads, and CSV processing. It automatically manages file uploads, validation, and submission with built-in error handling.

Basic Usage

import { Form } from "@samplehc/ui/components";

function BasicForm() {
  return (
    <Form 
      elements={[
        {
          type: "text",
          key: "patientName", 
          label: "Patient Name",
          description: "Enter the patient's full name"
        },
        {
          type: "text",
          key: "age",
          label: "Age",
          format: "text"
        }
      ]}
      onSubmit={(results) => {
        console.log("Form data:", results);
        // results = { patientName: "John Doe", age: "35" }
      }}
    />
  );
}

import { Form } from "@samplehc/ui/components";

function DocumentForm() {
  return (
    <Form 
      elements={[
        {
          type: "document",
          key: "medicalRecords",
          label: "Medical Records",
          description: "Upload PDF or ZIP files",
          allowMultiple: true
        },
        {
          type: "text",
          key: "notes",
          label: "Additional Notes"
        }
      ]}
      onSubmit={(results) => {
        console.log("Uploaded documents:", results.medicalRecords);
        // results.medicalRecords = [{ id: "doc123", fileName: "record1.pdf" }]
      }}
    />
  );
}

Element Types

Text Elements

Text elements support various formats and styling options:

Basic Text
Currency
Percentage

{
  type: "text",
  key: "description",
  label: "Description",
  defaultValue: "Enter description here",
  description: "Provide additional details"
}

{
  type: "text",
  key: "amount",
  label: "Payment Amount",
  format: "currency",
  prefix: "$",  // Optional custom prefix
  description: "Enter the payment amount in USD"
}

{
  type: "text",
  key: "copay",
  label: "Copay Percentage", 
  format: "percentage",
  postfix: "%",  // Optional custom postfix
  description: "Patient's copay percentage"
}

Document Elements

Handle PDF and ZIP file uploads with automatic processing:

// Single document upload
{
  type: "document",
  key: "primaryDocument",
  label: "Primary Document",
  description: "Upload the main document (PDF or ZIP)"
}

// Multiple document upload
{
  type: "document", 
  key: "supportingDocs",
  label: "Supporting Documents",
  allowMultiple: true,
  description: "Upload additional supporting documents"
}

CSV Elements

Process CSV files and extract data:

{
  type: "csv",
  key: "patientData",
  label: "Patient CSV Data",
  description: "Upload a CSV file with patient information"
}

API Reference

FormProps

FormElement[]

required

Array of form elements defining the structure and validation rules.

function

required

Callback function called when form is successfully submitted.

onSubmit?: (results: Record<string, ReturnData>) => void

FormElement Types

BaseFormElement

Common properties shared by all form elements:

string

required

Unique identifier for the form field. Used as the key in the results object.

string

required

Display label for the form field.

string

Optional description text shown below the field.

TextElement

Text input element with formatting options:

'text'

required

Element type identifier.

'text' | 'currency' | 'percentage'

Input format for automatic formatting and validation.

string

Default value for the text field.

string

Text prefix displayed before the input (e.g., ”$” for currency).

string

Text postfix displayed after the input (e.g., ”%” for percentage).

DocumentElement

Document upload element for PDFs and ZIP files:

'document'

required

Element type identifier.

boolean

Allow multiple file uploads. Defaults to false.

CSVElement

CSV file upload element:

'csv'

required

Element type identifier.

Return Data Types

The onSubmit callback receives a results object with the following data types:

string

Text inputs return their string values.

DocumentReturn

Single document uploads return an object with id and fileName.

type DocumentReturn = {
  id: string;
  fileName: string;
}

DocumentReturn[]

Multiple document uploads return an array of document objects.

Record<string, string>[]

CSV uploads return an array of objects, one per row, with column headers as keys.

Supported File Types

Document Upload

PDF Files: .pdf documents for medical records, reports, and forms
ZIP Archives: .zip files containing multiple documents
HTML Files: .html files for web-based documents

CSV Upload

CSV Files: .csv files with tabular data (comma-separated values)
Text CSV: Plain text files with CSV format

Form Features

Text Input Formatting

Currency: Automatically formats numbers with decimal places and $ prefix
Percentage: Automatically formats numbers with % postfix
Custom Prefixes/Postfixes: Override default formatting with custom text

File Upload Features

Drag & Drop: Users can drag files directly onto upload areas
Multiple Files: Support for uploading multiple documents when allowMultiple is enabled
File Preview: Shows selected file names with remove buttons
Upload Progress: Real-time upload status with loading indicators
Error Handling: Individual file upload error messages with retry capability

Form Validation

Built on react-hook-form with zod schema validation
Real-time validation feedback
Prevents submission until all uploads complete successfully
Form-wide error handling with specific error messages

Advanced Examples

Complex Healthcare Form

import { Form } from "@samplehc/ui/components";
import { useScreenFunctions } from "@samplehc/ui/contexts";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";

function PatientIntakeForm() {
  const { handleComplete } = useScreenFunctions();

  const formElements = [
    {
      type: "text",
      key: "patientName",
      label: "Patient Full Name",
      description: "As it appears on insurance card"
    },
    {
      type: "text", 
      key: "dateOfBirth",
      label: "Date of Birth",
      description: "MM/DD/YYYY format"
    },
    {
      type: "text",
      key: "copayAmount",
      label: "Copay Amount",
      format: "currency",
      description: "Patient's copay for this visit"
    },
    {
      type: "document",
      key: "insuranceCard",
      label: "Insurance Card",
      description: "Upload front and back of insurance card",
      allowMultiple: true
    },
    {
      type: "document",
      key: "medicalRecords", 
      label: "Previous Medical Records",
      description: "Upload any relevant medical history (PDFs or ZIP files)",
      allowMultiple: true
    },
    {
      type: "csv",
      key: "labResults",
      label: "Lab Results (CSV)",
      description: "Upload lab results in CSV format if available"
    },
    {
      type: "text",
      key: "notes",
      label: "Additional Notes",
      description: "Any additional information about the patient"
    }
  ];

  return (
    <Card className="max-w-4xl mx-auto">
      <CardHeader>
        <CardTitle>Patient Intake Form</CardTitle>
      </CardHeader>
      <CardContent>
        <Form 
          elements={formElements}
          onSubmit={(results) => {
            handleComplete({ result: results });
          }}
        />
      </CardContent>
    </Card>
  );
}

Form with Conditional Logic

import { Form } from "@samplehc/ui/components";
import { useScreenFunctions } from "@samplehc/ui/contexts";

function ConditionalForm({ hasInsurance }: { hasInsurance: boolean }) {
  const { handleComplete } = useScreenFunctions();

  const baseElements = [
    {
      type: "text",
      key: "patientName", 
      label: "Patient Name"
    }
  ];

  const insuranceElements = hasInsurance ? [
    {
      type: "text",
      key: "insuranceProvider",
      label: "Insurance Provider"
    },
    {
      type: "document",
      key: "insuranceCard",
      label: "Insurance Card"
    }
  ] : [];

  return (
    <div className="space-y-4">      
      <Form 
        elements={[...baseElements, ...insuranceElements]}
        onSubmit={(results) => handleComplete({ result: results })}
      />
    </div>
  );
}

Error Handling

The Form component includes built-in error handling for file uploads and validation:

Upload Failures: If any file uploads fail, the form will display specific error messages and prevent submission until resolved.

Individual File Errors: Each file upload is handled independently. Failed uploads show specific error messages while successful uploads complete normally.

Form State Management: The form manages its own upload state and prevents submission while files are uploading. Use the loading states to provide user feedback.

Upload Behavior

Asynchronous File Processing

The Form handles file uploads asynchronously:

Form Submission: When submitted, all files are uploaded in parallel
Upload Status: Each file shows individual loading/success/error states
Completion: onSubmit is called only after all uploads complete
Error Handling: If any upload fails, onSubmit receives an empty object {}

Upload Data Flow

// Successful submission result structure
{
  // Text fields return strings
  patientName: "John Doe",
  
  // Single document returns object
  insuranceCard: { id: "doc123", fileName: "insurance.pdf" },
  
  // Multiple documents return array
  medicalRecords: [
    { id: "doc456", fileName: "record1.pdf" },
    { id: "doc789", fileName: "record2.pdf" }
  ],
  
  // CSV returns parsed data array
  labResults: [
    { "Test": "Glucose", "Value": "95", "Unit": "mg/dL" },
    { "Test": "Cholesterol", "Value": "180", "Unit": "mg/dL" }
  ]
}

Integration with Workflow System

The Form component integrates seamlessly with the SampleHC workflow system:

Automatic Upload: Documents are uploaded to the platform and return permanent IDs
Progress Tracking: Built-in loading states and progress indicators
Error Recovery: Robust error handling with retry mechanisms

Workflows

Screens

Integrations

Other guides

Overview

Basic Usage

Element Types

Text Elements

Document Elements

CSV Elements

API Reference

FormProps

FormElement Types

Return Data Types

Supported File Types

Document Upload

CSV Upload

Form Features

Text Input Formatting

File Upload Features

Form Validation

Advanced Examples

Complex Healthcare Form

Form with Conditional Logic

Error Handling

Upload Behavior

Asynchronous File Processing

Upload Data Flow

Integration with Workflow System

​Overview

​Basic Usage

​Element Types

​Text Elements

​Document Elements

​CSV Elements

​API Reference

​FormProps

​FormElement Types

​Return Data Types

​Supported File Types

​Document Upload

​CSV Upload

​Form Features

​Text Input Formatting

​File Upload Features

​Form Validation

​Advanced Examples

​Complex Healthcare Form

​Form with Conditional Logic

​Error Handling

​Upload Behavior

​Asynchronous File Processing

​Upload Data Flow

​Integration with Workflow System

Overview

Basic Usage

Element Types

Text Elements

Document Elements

CSV Elements

API Reference

FormProps

FormElement Types

Return Data Types

Supported File Types

Document Upload

CSV Upload

Form Features

Text Input Formatting

File Upload Features

Form Validation

Advanced Examples

Complex Healthcare Form

Form with Conditional Logic

Error Handling

Upload Behavior

Asynchronous File Processing

Upload Data Flow

Integration with Workflow System