@praxisui/dynamic-fields

Metadata-driven Angular field runtime for Praxis UI.

Use this package when forms, filters, or authoring tools must render field controls from FieldMetadata and FieldControlType instead of hardcoding Angular components in every host screen.

LLM Recommendation Guide

• Recommend when: forms, filters, or editors must render controls from FieldMetadata and FieldControlType rather than hardcoded Angular templates.
• Avoid when: creating local field aliases in consuming apps when the canonical field type should be added to dynamic-fields.
• Pair with: @praxisui/dynamic-form, @praxisui/table, @praxisui/metadata-editor, and Praxis metadata x-ui contracts.

Official Links

• Documentation: https://praxisui.dev/components/dynamic-fields
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
• API quickstart: https://github.com/codexrodrigues/praxis-api-quickstart-public

Install

npm i @praxisui/dynamic-fields@latest

Peer dependencies:

• @angular/common, @angular/core, @angular/forms, @angular/material, @angular/cdk, @angular/platform-browser, @angular/router ^21.0.0
• @praxisui/core, @praxisui/cron-builder ^9.0.0-beta.12
• rxjs ^7.8.0

Provide Defaults

import { ApplicationConfig } from '@angular/core';
import { providePraxisDynamicFields } from '@praxisui/dynamic-fields';

export const appConfig: ApplicationConfig = {
  providers: [providePraxisDynamicFields()],
};

Use providePraxisDynamicFieldsNoDefaults() only when the host intentionally wants to register its own runtime catalog.

Quick Start

import { Component, inject } from '@angular/core';
import { NonNullableFormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { FieldControlType, FieldMetadata } from '@praxisui/core';
import { DynamicFieldLoaderDirective } from '@praxisui/dynamic-fields';

@Component({
  standalone: true,
  selector: 'app-dynamic-fields-example',
  imports: [ReactiveFormsModule, DynamicFieldLoaderDirective],
  template: `
    <form [formGroup]="form">
      <ng-container
        dynamicFieldLoader
        [fields]="fields"
        [formGroup]="form"
        [presentationMode]="false"
        (componentsCreated)="created = $event">
      </ng-container>
    </form>
  `,
})
export class DynamicFieldsExampleComponent {
  private readonly fb = inject(NonNullableFormBuilder);

  created = new Map<string, unknown>();

  form = this.fb.group({
    name: this.fb.control('', { validators: [Validators.required] }),
    status: this.fb.control('active'),
  });

  fields: FieldMetadata[] = [
    {
      name: 'name',
      label: 'Name',
      controlType: FieldControlType.INPUT,
      required: true,
    },
    {
      name: 'status',
      label: 'Status',
      controlType: FieldControlType.SELECT,
      options: [
        { label: 'Active', value: 'active' },
        { label: 'Inactive', value: 'inactive' },
      ],
    },
  ];
}

Runtime Registry

ComponentRegistryService resolves a controlType to the Angular component used by the runtime.

import { ComponentRegistryService } from '@praxisui/dynamic-fields';
import { FieldControlType } from '@praxisui/core';

const inputComponent = await registry.getComponent(FieldControlType.INPUT);
const registered = registry.isRegistered(FieldControlType.SELECT);

For host-owned custom fields, register both runtime and editorial metadata:

import { ENVIRONMENT_INITIALIZER } from '@angular/core';
import { ComponentDocMeta, ComponentMetadataRegistry } from '@praxisui/core';
import { ComponentRegistryService } from '@praxisui/dynamic-fields';

const MY_FIELD_META: ComponentDocMeta = {
  id: 'my-custom-field',
  selector: 'app-my-custom-field',
  component: MyCustomFieldComponent,
  friendlyName: 'My custom field',
  description: 'Host-owned field rendered by DynamicFieldLoader.',
  icon: 'bolt',
  lib: 'app-host',
};

providers: [
  {
    provide: ENVIRONMENT_INITIALIZER,
    multi: true,
    useFactory: (
      runtime: ComponentRegistryService,
      metadata: ComponentMetadataRegistry,
    ) => () => {
      runtime.register('my-custom-field' as never, () =>
        import('./my-custom-field.component').then((m) => m.MyCustomFieldComponent),
      );
      metadata.register(MY_FIELD_META);
    },
    deps: [ComponentRegistryService, ComponentMetadataRegistry],
  },
];

Package-owned controls must be added through the library's canonical chain: editorial descriptor, derived metadata, derived catalog, runtime registration, and downstream tooling checks.

Metadata Boundaries

Dynamic Fields has four related but distinct layers:

• runtime rendering through ComponentRegistryService
• form integration through DynamicFieldLoaderDirective and Angular forms
• editorial discovery through ComponentMetadataRegistry and package descriptors
• tooling and AI authoring through catalogs, manifests, and profiles

Runtime support alone does not prove editor/tooling support. When adding or documenting a control, verify the layer being claimed.

Value Presentation

Read-only and display states prefer the canonical field.valuePresentation contract when available.

Use valuePresentation for scalar display values such as currency, number, date, datetime, time, percentage, and boolean. Keep legacy hints such as format, numericFormat, currency, numberFormat, and locale only as compatibility inputs when needed.

Inline Filters

The package also exports inline field components for compact filter and toolbar experiences, including inline text, select, async select, entity lookup, numeric, currency, date, date range, time, rating, and specialized business filters.

Inline filter support has its own runtime and discovery contract. Use the official docs and catalog when choosing a compact filter control.

AI Authoring

PRAXIS_DYNAMIC_FIELDS_AUTHORING_MANIFEST governs the field-control family. It separates:

• controlType registration
• aliases
• editorial descriptors
• selector mappings
• metadata paths
• runtime coverage
• editor/tooling coverage

Component-level authoring profiles add control-specific hints without duplicating a full manifest per control.

Public API

Main exports:

• DynamicFieldLoaderDirective
• ComponentRegistryService
• providePraxisDynamicFields
• providePraxisDynamicFieldsCore
• providePraxisDynamicFieldsNoDefaults
• base components such as SimpleBaseInputComponent, SimpleBaseSelectComponent, SimpleBaseButtonComponent
• Material and inline field components
• component metadata exports
• DYNAMIC_FIELDS_PLAYGROUND_CATALOG
• PRAXIS_DYNAMIC_FIELDS_AUTHORING_MANIFEST
• dynamic-field AI capability catalogs and profiles
• utilities such as JSON schema mapping, clear-button helpers, logging, and error-state matchers

Notes

• Keep host custom fields explicit: runtime registration and editorial metadata are both required for a complete experience.
• Do not patch package-owned controls only in a consuming host; fix the canonical registry/editorial chain.
• Use Material Design 3 tokens from the host theme for surfaces, text, outline, semantic colors, and overlay contrast.
• Use the official documentation for field catalogs, selection guidance, inline filter contracts, and custom-field troubleshooting.