@expeed/ngx-dyna-form

@expeed/ngx-dyna-form

A dynamic form renderer for Angular that builds reactive forms from JSON Schema definitions. Supports various input types, validation, nested objects, and arrays.

Features

• JSON Schema-Driven: Automatically render forms from JSON Schema
• Display Type Hints: Use x-display-type to control input rendering
• Multiple Input Types: textbox, textarea, richtext, datepicker, dropdown, radio, checkbox, toggle, stepper, tags, multiselect, multiselect-dropdown
• Rich Text Editor: Quill integration for HTML content editing
• Nested Objects: Render nested object properties as fieldsets
• Array Support: Dynamic arrays with add/remove functionality
• Validation: Apply validators from schema constraints (required, minLength, maxLength, pattern, min, max)
• Grid Layout: Configurable columns with field-level width control
• Field Exclusion: Exclude specific fields from rendering

Installation

npm install @expeed/ngx-dyna-form

Peer Dependencies

npm install @angular/cdk @angular/material ngx-quill quill

Quill CSS Setup

Add Quill styles to your angular.json:

{
  "styles": [
    "node_modules/quill/dist/quill.core.css",
    "node_modules/quill/dist/quill.snow.css"
  ]
}

Usage

Basic Usage

import { Component, signal } from '@angular/core';
import { DynamicFormComponent, DynamicFormSchema } from '@expeed/ngx-dyna-form';

@Component({
  selector: 'app-form',
  standalone: true,
  imports: [DynamicFormComponent],
  template: `
    <dyna-form
      [schema]="schema"
      [values]="formValues()"
      (valuesChange)="onValuesChange($event)"
      (validChange)="onValidChange($event)"
    />

    <button [disabled]="!isValid()" (click)="submit()">
      Submit
    </button>
  `
})
export class FormComponent {
  schema: DynamicFormSchema = {
    type: 'object',
    title: 'Contact Form',
    properties: {
      name: {
        type: 'string',
        title: 'Full Name',
        minLength: 2
      },
      email: {
        type: 'string',
        title: 'Email',
        format: 'email'  // Auto-renders as email input with validation
      },
      message: {
        type: 'string',
        title: 'Message',
        'x-display-type': 'textarea'
      }
    },
    required: ['name', 'email']
  };

  formValues = signal<Record<string, unknown>>({});
  isValid = signal(false);

  onValuesChange(values: Record<string, unknown>): void {
    this.formValues.set(values);
  }

  onValidChange(valid: boolean): void {
    this.isValid.set(valid);
  }

  submit(): void {
    console.log('Submitting:', this.formValues());
  }
}

With Grid Layout

<dyna-form
  [schema]="schema"
  [values]="formValues()"
  [columns]="2"
  [defaultFieldColumns]="1"
  [fieldColumns]="{ 'description': 2, 'address.street': 2 }"
  [excludeFields]="['internalId', 'metadata']"
  (valuesChange)="onValuesChange($event)"
  (validChange)="onValidChange($event)"
/>

Using ViewChild for Imperative Access

import { ViewChild } from '@angular/core';
import { DynamicFormComponent } from '@expeed/ngx-dyna-form';

@ViewChild(DynamicFormComponent) dynaForm!: DynamicFormComponent;

submit(): void {
  if (this.dynaForm.isValid()) {
    const data = this.dynaForm.getValue();
    this.apiService.save(data).subscribe();
  } else {
    this.dynaForm.markAllTouched(); // Show validation errors
  }
}

API Reference

DynamicFormComponent

Inputs

Input	Type	Default	Description
schema	DynamicFormSchema	null	JSON Schema defining the form
values	Record<string, unknown>	{}	Initial form values
columns	1 | 2	2	Number of grid columns
defaultFieldColumns	number	1	Default column span for fields
fieldColumns	Record<string, number>	{}	Per-field column span overrides
excludeFields	string[]	[]	Field paths to exclude
emptyMessage	string	''	Message when no fields

Outputs

Output	Type	Description
valuesChange	EventEmitter<Record<string, unknown>>	Emits on value changes
validChange	EventEmitter<boolean>	Emits on validity changes

Public Methods

Method	Returns	Description
getValue()	Record<string, unknown>	Get current form values
isValid()	boolean	Check if form is valid
markAllTouched()	void	Mark all fields as touched

Schema Reference

The DynamicFormSchema follows JSON Schema (draft 2020-12) with x-display-type extension:

interface DynamicFormSchema {
  type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
  title?: string;                    // Field label
  description?: string;              // Help text shown below field
  default?: unknown;                 // Default value

  // Object properties
  properties?: Record<string, DynamicFormSchema>;
  required?: string[];               // Required field names

  // Array properties
  items?: DynamicFormSchema;         // Schema for array items
  minItems?: number;
  maxItems?: number;

  // String constraints
  minLength?: number;
  maxLength?: number;
  pattern?: string;                  // Regex pattern
  format?: 'email' | 'uri' | 'url' | 'date' | 'date-time' | 'time';

  // Number constraints
  minimum?: number;
  maximum?: number;

  // Allowed values
  enum?: unknown[];                  // Simple values
  oneOf?: Array<{ const: unknown; title?: string }>;  // Labeled values

  // Display hint
  'x-display-type'?: string;         // See Display Types table
}

Note: For arrays with enum options (multiselect), place enum/oneOf on items and x-display-type on the array:

{
  type: 'array',
  title: 'Colors',
  'x-display-type': 'multiselect',  // Display type on array
  items: {
    type: 'string',
    enum: ['red', 'green', 'blue']   // Options on items
  }
}

Display Types

Control how fields are rendered using x-display-type:

Display Type	Description	Field Type
textbox	Single-line text input	string
textarea	Multi-line text input	string
richtext	Quill rich text editor	string
dropdown	Select dropdown	string (enum)
radio	Radio button group	string (enum)
datepicker	Date picker	date
datetimepicker	Date and time picker	date
timepicker	Time picker	time
stepper	Number stepper with +/-	number
checkbox	Checkbox	boolean
toggle	Toggle switch	boolean
multiselect	Checkbox group	array (enum)
multiselect-dropdown	Dropdown with checkboxes	array (enum)
tags	Tag input	array (string)

Auto-Inferred Display Types

The following display types are automatically inferred from schema properties:

Schema	Inferred Display Type	Renders As
format: 'email'	email	<input type="email">
format: 'uri' / 'url'	url	<input type="url">
format: 'date' / 'date-time'	datepicker	<input type="date">
format: 'time'	timepicker	<input type="time">
type: 'array' + items.enum	multiselect	Checkbox group
type: 'array' + items.type: 'string'	tags	Tag input
type: 'array' + items.type: 'object'	array-objects	Repeatable fieldset
type: 'object' + properties	fieldset	Nested fieldset

Schema Example with Display Types

const schema: DynamicFormSchema = {
  type: 'object',
  properties: {
    bio: {
      type: 'string',
      title: 'Biography',
      'x-display-type': 'richtext'
    },
    email: {
      type: 'string',
      title: 'Email',
      format: 'email'  // Auto-infers email input type
    },
    website: {
      type: 'string',
      title: 'Website',
      format: 'uri'  // Auto-infers url input type
    },
    birthDate: {
      type: 'string',
      title: 'Birth Date',
      format: 'date'  // Auto-infers datepicker
    },
    country: {
      type: 'string',
      title: 'Country',
      enum: ['US', 'UK', 'CA'],
      'x-display-type': 'dropdown'
    },
    notifications: {
      type: 'boolean',
      title: 'Enable Notifications',
      'x-display-type': 'toggle'
    },
    age: {
      type: 'integer',
      title: 'Age',
      minimum: 0,
      maximum: 150,
      'x-display-type': 'stepper'
    },
    skills: {
      type: 'array',
      title: 'Skills',
      items: { type: 'string' }  // Auto-infers tags input
    }
  }
};

Allowed Values (Enum/OneOf)

Define allowed values for dropdowns, radio buttons, and multiselect fields:

// Simple enum - values are used as both value and label
{
  type: 'string',
  title: 'Size',
  enum: ['small', 'medium', 'large'],
  'x-display-type': 'dropdown'
}

// Labeled values using oneOf - separate value and display label
{
  type: 'string',
  title: 'Size',
  oneOf: [
    { const: 'sm', title: 'Small' },
    { const: 'md', title: 'Medium' },
    { const: 'lg', title: 'Large' }
  ],
  'x-display-type': 'dropdown'
}

// Multiselect with labeled values
{
  type: 'array',
  title: 'Categories',
  items: {
    type: 'string',
    oneOf: [
      { const: 'tech', title: 'Technology' },
      { const: 'health', title: 'Healthcare' },
      { const: 'finance', title: 'Finance' }
    ]
  },
  'x-display-type': 'multiselect'
}

The oneOf format allows the form to display user-friendly labels while storing machine-readable values.

Nested Objects

Nested objects render as fieldsets:

const schema: DynamicFormSchema = {
  type: 'object',
  properties: {
    name: { type: 'string', title: 'Name' },
    address: {
      type: 'object',
      title: 'Address',
      properties: {
        street: { type: 'string', title: 'Street' },
        city: { type: 'string', title: 'City' },
        zip: { type: 'string', title: 'ZIP Code' }
      },
      required: ['street', 'city']
    }
  }
};

Array of Objects

Arrays of objects render with add/remove functionality:

const schema: DynamicFormSchema = {
  type: 'object',
  properties: {
    contacts: {
      type: 'array',
      title: 'Contacts',
      minItems: 1,
      maxItems: 5,
      items: {
        type: 'object',
        properties: {
          name: { type: 'string', title: 'Name' },
          email: { type: 'string', title: 'Email', format: 'email' }
        },
        required: ['name']
      }
    }
  }
};

Field Exclusion

Exclude fields using paths with wildcard support:

// Exclude specific fields
excludeFields: ['password', 'internalId']

// Exclude nested fields
excludeFields: ['address.country', 'metadata.createdAt']

// Exclude array item fields (wildcard)
excludeFields: ['contacts[*].phone']

Validation

Validators are automatically applied from schema constraints:

Schema Property	Validator
required (in parent)	Required
minLength	Min length
maxLength	Max length
pattern	Regex pattern
minimum	Min value
maximum	Max value
format: 'email'	Email format
format: 'uri'	URL format

Styling

Customize with CSS custom properties:

dyna-form {
  --df-color-primary: #3b82f6;
  --df-color-error: #ef4444;
  --df-color-text-primary: #1f2937;
  --df-color-text-secondary: #6b7280;
  --df-color-border: #e5e7eb;
  --df-color-surface: #ffffff;
  --df-radius-default: 0.375rem;
  --df-font-size-sm: 0.875rem;
}

Exports

// Components
export { DynamicFormComponent } from './lib/components/dynamic-form/dynamic-form.component';

// Types
export { DynamicFormSchema } from './lib/components/dynamic-form/dynamic-form.component';
export { FormField } from './lib/components/dynamic-form/dynamic-form.component';

Requirements

• Angular 21+
• ngx-quill 30+ (for rich text)
• Quill 2.0+

License

Apache 2.0