0
# NGX-Formly Core
1

2
NGX-Formly Core is the foundational package of the ngx-formly library, providing essential infrastructure for building dynamic, JSON-powered forms in Angular applications. It offers automatic form generation from JSON schemas, custom field types, validation rules, wrappers, and extensions built on top of Angular Reactive Forms.
3

4
## Package Information
5

6
- **Package Name**: @ngx-formly/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ngx-formly/core`
10

11
## Core Imports
12

13
```typescript
14
import { FormlyModule, FormlyFieldConfig, FormlyFormOptions } from "@ngx-formly/core";
15
```
16

17
For standalone components:
18

19
```typescript
20
import { FormlyForm, FormlyField, provideFormlyCore } from "@ngx-formly/core";
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Component } from '@angular/core';
27
import { FormGroup } from '@angular/forms';
28
import { FormlyFieldConfig } from '@ngx-formly/core';
29

30
@Component({
31
  selector: 'app-example',
32
  template: `
33
    <form [formGroup]="form" (ngSubmit)="onSubmit(model)">
34
      <formly-form [form]="form" [fields]="fields" [model]="model"></formly-form>
35
      <button type="submit">Submit</button>
36
    </form>
37
  `,
38
})
39
export class AppComponent {
40
  form = new FormGroup({});
41
  model = { email: '', name: '' };
42
  fields: FormlyFieldConfig[] = [
43
    {
44
      key: 'email',
45
      type: 'input',
46
      props: {
47
        label: 'Email',
48
        placeholder: 'Enter email',
49
        required: true,
50
      },
51
    },
52
    {
53
      key: 'name',
54
      type: 'input',
55
      props: {
56
        label: 'Name',
57
        placeholder: 'Enter name',
58
        required: true,
59
      },
60
    },
61
  ];
62

63
  onSubmit(model: any) {
64
    console.log(model);
65
  }
66
}
67
```
68

69
## Architecture
70

71
NGX-Formly Core is built around several key components:
72

73
- **Form Components**: `FormlyForm` and `FormlyField` for rendering dynamic forms
74
- **Configuration System**: Extensible configuration for field types, wrappers, and validators
75
- **Services**: `FormlyConfig` for global configuration and `FormlyFormBuilder` for form construction
76
- **Extension System**: Plugin architecture for extending form behavior
77
- **Type System**: Base classes for creating custom field types and wrappers
78

79
## Capabilities
80

81
### Configuration & Module Setup
82

83
Module setup, configuration functions, and dependency injection for integrating Formly into Angular applications.
84

85
```typescript { .api }
86
class FormlyModule {
87
  static forRoot(config?: ConfigOption): ModuleWithProviders<FormlyModule>;
88
  static forChild(config?: ConfigOption): ModuleWithProviders<FormlyModule>;
89
}
90

91
function provideFormlyCore(configs?: ConfigOption | ConfigOption[]): Provider;
92
```
93

94
[Configuration & Module Setup](./configuration.md)
95

96
### Field Components
97

98
Core components for rendering dynamic forms with field configuration support.
99

100
```typescript { .api }
101
@Component({ selector: 'formly-form' })
102
export class FormlyForm {
103
  @Input() form: FormGroup | UntypedFormGroup;
104
  @Input() fields: FormlyFieldConfig[];
105
  @Input() model: any;
106
  @Input() options: FormlyFormOptions;
107
}
108

109
@Component({ selector: 'formly-field' })
110
export class FormlyField {
111
  @Input() field: FormlyFieldConfig;
112
}
113
```
114

115
[Field Components](./field-components.md)
116

117
### Field Types
118

119
Base classes and interfaces for creating custom field types, array types, and wrappers.
120

121
```typescript { .api }
122
export abstract class FieldType<F extends FormlyFieldConfig = FormlyFieldConfig> {
123
  field: F;
124
  formControl: AbstractControl;
125
  to: F['props'];
126
  showError?: boolean;
127
  id?: string;
128
  formState?: any;
129
}
130

131
export abstract class FieldArrayType<F extends FormlyFieldConfig = FormlyFieldConfig> extends FieldType<F> {
132
  add(i?: number, initialModel?: any, options?: FormlyFieldConfig): void;
133
  remove(i: number): void;
134
}
135
```
136

137
[Field Types](./field-types.md)
138

139
### Services
140

141
Core services for configuration management and form building functionality.
142

143
```typescript { .api }
144
@Injectable()
145
export class FormlyConfig {
146
  addConfig(config: ConfigOption): void;
147
  setType(options: FieldTypeConfig | FieldTypeConfig[]): void;
148
  setWrapper(options: WrapperOption | WrapperOption[]): void;
149
  setValidator(options: ValidatorOption | ValidatorOption[]): void;
150
  getType(name: string): FieldTypeConfig;
151
  getValidator(name: string): ValidatorOption;
152
  getWrapper(name: string): WrapperOption;
153
}
154

155
@Injectable()
156
export class FormlyFormBuilder {
157
  buildForm(form: FormGroup | UntypedFormGroup, fields: FormlyFieldConfig[], model: any, options: FormlyFormOptions): void;
158
}
159
```
160

161
[Services](./services.md)
162

163
### Validation
164

165
Validation system with custom validators, validation messages, and error handling.
166

167
```typescript { .api }
168
@Component({ selector: 'formly-validation-message' })
169
export class FormlyValidationMessage {
170
  @Input() field: FormlyFieldConfig;
171
}
172

173
interface ValidatorOption {
174
  name: string;
175
  validation: ValidatorFn | AsyncValidatorFn;
176
  options?: { [id: string]: any };
177
}
178
```
179

180
[Validation](./validation.md)
181

182
### Utilities
183

184
Utility functions and helpers for form manipulation, data binding, and reactive programming.
185

186
```typescript { .api }
187
function defineHiddenProp(field: any, prop: string, defaultValue: any): void;
188
function getFieldValue(field: FormlyFieldConfig): any;
189
function reverseDeepMerge(dest: any, ...args: any[]): any;
190
function clone(value: any): any;
191
function hasKey(field: FormlyFieldConfig): boolean;
192
```
193

194
[Utilities](./utilities.md)
195

196
### JSON Schema Integration
197

198
JSON Schema support for automatic form generation from schema definitions.
199

200
```typescript { .api }
201
class FormlyJsonschema {
202
  toFieldConfig(schema: JSONSchema7, options?: FormlyJsonschemaOptions): FormlyFieldConfig;
203
}
204

205
interface FormlyJsonschemaOptions {
206
  map?: (mappedField: FormlyFieldConfig, mapSource: JSONSchema7) => FormlyFieldConfig;
207
  strict?: boolean;
208
}
209
```
210

211
[JSON Schema](./json-schema.md)
212

213
### Select Options
214

215
Utilities for handling select field options with observable support.
216

217
```typescript { .api }
218
@Pipe({ name: 'formlySelectOptions' })
219
export class FormlySelectOptionsPipe {
220
  transform(options: any, field?: FormlyFieldConfig): Observable<FormlySelectOption[]>;
221
}
222

223
interface FormlySelectOption {
224
  label: string;
225
  value: any;
226
  disabled?: boolean;
227
  group?: string;
228
}
229
```
230

231
[Select Options](./select.md)
232

233
### Testing Utilities
234

235
Utilities for testing Formly components and fields.
236

237
```typescript { .api }
238
function createComponent<T>(options: IComponentOptions<T>): FixtureUtils;
239
function createFieldComponent(field: FormlyFieldConfig, config?: any): FixtureUtils;
240

241
interface FixtureUtils {
242
  fixture: ComponentFixture<any>;
243
  component: any;
244
  detectChanges(): void;
245
  query<T>(selector: string): T;
246
}
247
```
248

249
[Testing](./testing.md)
250

251
## Types
252

253
### Core Configuration Types
254

255
```typescript { .api }
256
interface FormlyFieldConfig<Props = FormlyFieldProps & { [additionalProperties: string]: any }> {
257
  key?: string | number | (string | number)[];
258
  type?: string | Type<FieldType>;
259
  props?: Props;
260
  templateOptions?: FormlyTemplateOptions; // @deprecated
261
  defaultValue?: any;
262
  validators?: FormlyFieldConfigValidators;
263
  validation?: FormlyFieldConfigValidators;
264
  asyncValidators?: FormlyFieldConfigValidators;
265
  hide?: boolean | FieldExpression<boolean>;
266
  hideExpression?: boolean | string | ((field: FormlyFieldConfig) => boolean);
267
  resetOnHide?: boolean;
268
  expressions?: FieldExpressions;
269
  className?: string;
270
  fieldGroupClassName?: string;
271
  fieldGroup?: FormlyFieldConfig[];
272
  fieldArray?: FormlyFieldConfig | ((field: FormlyFieldConfig) => FormlyFieldConfig);
273
  template?: string;
274
  wrappers?: (string | Type<FieldWrapper>)[];
275
  parsers?: Array<(value: any, field: FormlyFieldConfig) => any>;
276
  modelOptions?: {
277
    debounce?: { default: number } & { [key: string]: number };
278
    updateOn?: 'change' | 'blur' | 'submit';
279
  };
280
  hooks?: FormlyHookConfig;
281
  focus?: boolean;
282
  id?: string;
283
  name?: string;
284
  
285
  // Readonly properties set by the system
286
  readonly model?: any;
287
  readonly parent?: FormlyFieldConfig;
288
  readonly options?: FormlyFormOptions;
289
  readonly form?: UntypedFormGroup | UntypedFormArray;
290
  readonly formControl?: AbstractControl;
291

292
  // Method for accessing child fields
293
  get?(key: FormlyFieldConfig['key']): FormlyFieldConfig;
294
}
295

296
interface FormlyFormOptions {
297
  formState?: any;
298
  fieldChanges?: Subject<FormlyValueChangeEvent>;
299
  fieldTransform?: (fields: FormlyFieldConfig[], model: any, form: FormGroup | UntypedFormGroup, options: FormlyFormOptions) => FormlyFieldConfig[];
300
  showError?: (field: FormlyFieldConfig) => boolean;
301
  resetOnHide?: boolean;
302
  parentForm?: FormGroupDirective | null;
303
  updateInitialValue?: (model?: any) => void;
304
  resetModel?: (model?: any) => void;
305
  checkExpressions?: (field: FormlyFieldConfig, ignoreCache?: boolean) => void;
306
  detectChanges?: (field: FormlyFieldConfig) => void;
307
  build?: (field?: FormlyFieldConfig) => FormlyFieldConfig[];
308
  _resolver?: ComponentFactoryResolver;
309
  _viewContainerRef?: ViewContainerRef;
310
  _markForCheck?: (field: FormlyFieldConfig) => void;
311
  _hiddenFieldsForCheck?: FormlyFieldConfig[];
312
  _initialModel?: any;
313
}
314

315
interface FormlyFieldProps {
316
  [additionalProperties: string]: any;
317
  label?: string;
318
  placeholder?: string;
319
  description?: string;
320
  hidden?: boolean;
321
  disabled?: boolean;
322
  required?: boolean;
323
  readonly?: boolean;
324
  attributes?: { [key: string]: any };
325
}
326

327
interface ConfigOption {
328
  types?: TypeOption[];
329
  wrappers?: WrapperOption[];
330
  validators?: ValidatorOption[];
331
  extensions?: ExtensionOption[];
332
  validationMessages?: ValidationMessageOption[];
333
  extras?: FormlyConfigExtras;
334
  presets?: PresetOption[];
335
}
336

337
interface TypeOption {
338
  name: string;
339
  component?: Type<FieldType>;
340
  wrappers?: string[];
341
  extends?: string;
342
  defaultOptions?: FormlyFieldConfig;
343
}
344

345
interface WrapperOption {
346
  name: string;
347
  component: Type<FieldWrapper>;
348
  types?: string[];
349
}
350

351
interface ValidatorOption {
352
  name: string;
353
  validation: FieldValidatorFn;
354
  options?: { [id: string]: any };
355
}
356

357
interface ExtensionOption {
358
  name: string;
359
  extension: FormlyExtension;
360
}
361

362
interface FormlyExtension<F extends FormlyFieldConfig = FormlyFieldConfig> {
363
  priority?: number;
364
  prePopulate?(field: F): void;
365
  onPopulate?(field: F): void;
366
  postPopulate?(field: F): void;
367
}
368

369
interface FormlyHookConfig {
370
  onInit?: FormlyHookFn | ((field: FormlyFieldConfig) => Observable<any>);
371
  onChanges?: FormlyHookFn;
372
  afterContentInit?: FormlyHookFn;
373
  afterViewInit?: FormlyHookFn;
374
  onDestroy?: FormlyHookFn;
375
}
376

377
type FormlyHookFn = (field: FormlyFieldConfig) => void;
378

379
interface FormlyValueChangeEvent {
380
  field: FormlyFieldConfig;
381
  type: string;
382
  value: any;
383
}
384

385
type FormlyAttributeEvent = (field: FormlyFieldConfig, event?: Event) => void;
386

387
interface FormlyTemplate {
388
  name: string;
389
  template: TemplateRef<any>;
390
}
391

392
interface FormlyFieldConfigCache extends FormlyFieldConfig {
393
  _expressions?: { [property: string]: any };
394
  _hide?: boolean;
395
  _componentRefs?: ComponentRef<FieldType>[];
396
  _keyPath?: { key: FormlyFieldConfig['key']; index?: number };
397
}
398

399
type FieldValidatorFn = (control: AbstractControl, field: FormlyFieldConfig, options?: any) => ValidationErrors | null;
400

401
interface FieldExpressions {
402
  [property: string]: string | ((field: FormlyFieldConfig) => any) | Observable<any>;
403
}
404

405
type FieldExpression<T = any> = string | ((field: FormlyFieldConfig) => T) | Observable<T>;
406

407
interface FormlyConfigExtras {
408
  checkExpressionOn?: 'modelChange' | 'changeDetectionCheck';
409
  lazyRender?: boolean;
410
  resetFieldOnHide?: boolean;
411
  renderFormlyFieldElement?: boolean;
412
  showError?: (field: FieldType) => boolean;
413
  immutable?: boolean;
414
  fieldTransform?: (fields: FormlyFieldConfig[], model: any, form: UntypedFormGroup | UntypedFormArray, options: FormlyFormOptions) => FormlyFieldConfig[];
415
  removeFormControlOnHide?: boolean;
416
}
417

418
interface PresetOption {
419
  name: string;
420
  config: ConfigOption;
421
}
422

423
interface ValidationMessageOption {
424
  name: string;
425
  message: string | ((error: any, field: FormlyFieldConfig) => string);
426
}
427
```