Form Builder

Form Builder creates schema-driven forms with a drag-and-drop builder, a runtime renderer, and provider-based registration for field types and field-specific settings panels.

Use it for admin-configurable forms, document templates, onboarding builders, tenant-specific field layouts, surveys, intake flows, and other places where product teams need to compose fields without changing Angular templates.

Hidden fields use type: 'hidden'. They render as native input type="hidden" controls in runtime forms, stay editable in the builder inspector, and are included in raw submitted values.

Builder inputs

Input	Type	Default
schema Two-way model containing the form title, sections, and fields.	ModelSignal<FormBuilderSchema>	createDefaultFormBuilderSchema()
paletteTitle Title shown above the field palette.	string	Fields
inspectorTitle Title shown above the field settings inspector.	string	Field properties

Builder events

Event	Description	Type
fieldSelected	Emitted when a canvas field is selected.	FormBuilderFieldChange
fieldAdded	Emitted when a field is inserted from the palette.	FormBuilderFieldChange
fieldRemoved	Emitted when a field is deleted from the canvas.	FormBuilderFieldChange

Renderer inputs

Input	Type	Default
schema^* Saved builder schema to render as an Angular reactive form.	FormBuilderSchema	–
flow Optional renderer-only presentation flow. When provided, it overrides schema.flow and can set up runtime steps without changing the saved schema.	FormBuilderFlow \| null	undefined
items Optional top-level field and section references to render. Use this with an external stepper to render only the selected step while keeping one renderer form.	FormBuilderLayoutItem[] \| null	undefined
value Two-way model for runtime form values.	Record<string, any>	{}
readonly Disables all controls and hides the submit button when used with showSubmit.	boolean	false
showSubmit Whether the renderer shows its built-in submit button.	boolean	true
submitLabel Text for the built-in submit button.	string	Submit
uploadCallback Optional upload handler used by upload and logo-upload fields. Overrides the global provider callback.	FormBuilderUploadCallback \| null	undefined

Upload callback examples

Pass one callback to FormRenderer. The callback receives the field definition, so it can return a single logo value for logo-upload and one or many file values for upload.

template.html

<ngs-form-renderer
  [schema]="schema"
  [uploadCallback]="uploadCallback"
  [(value)]="value"/>

component.ts

import { inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import {
  FormBuilderSchema,
  FormBuilderUploadCallback
} from '@ngstarter-ui/components/form-builder';

private readonly http = inject(HttpClient);

readonly schema: FormBuilderSchema = {
  sections: [{
    id: 'files',
    title: 'Files',
    fields: [
      {
        id: 'attachments',
        name: 'attachments',
        type: 'upload',
        label: 'Attachments',
        multiple: true,
        settings: { accept: 'application/pdf,image/*' }
      },
      {
        id: 'company_logo',
        name: 'company_logo',
        type: 'logo-upload',
        label: 'Company logo'
      }
    ]
  }]
};

readonly uploadCallback: FormBuilderUploadCallback = async ({ field, files, multiple }) => {
  const uploadedFiles = await Promise.all(files.map(file => this.uploadFile(file)));

  // The same FormRenderer input handles both built-in upload field types.
  if (field.type === 'logo-upload') {
    return uploadedFiles[0] ?? null;
  }

  return multiple ? uploadedFiles : uploadedFiles[0] ?? null;
};

private async uploadFile(file: File) {
  const body = new FormData();
  body.append('file', file);

  return await firstValueFrom(
    this.http.post<{ name: string; url: string; size: number }>('/api/uploads', body)
  );
}

Renderer events

Event	Description	Type
formSubmit	Emitted with raw form value when the rendered form is valid and submitted.	Record<string, any>
formReady	Emitted after the renderer creates the FormGroup.	FormGroup

Provider helpers

Helper	Description	Returns
provideFormBuilder	Environment provider for custom items, custom fields, settings components, select data sources, and a global uploadCallback.	EnvironmentProviders
provideFormBuilderSelectDataSource	Provider helper for registering one named select data source that can be selected in the built-in select field inspector.	Provider
provideFormBuilderSelectDataSources	Provider helper for registering multiple named select data sources.	Provider[]
formBuilderItem	Helper for defining a palette item, including layout and static items, before passing it to provideFormBuilder.	FormBuilderItemDefinition
provideFormBuilderField	Provider helper for registering one custom field definition with FORM_BUILDER_FIELDS.	Provider
provideFormBuilderFields	Provider helper for registering multiple custom field definitions with FORM_BUILDER_FIELDS.	Provider[]
formBuilderField	Helper for defining a field type with defaults, lazy renderer, renderer-driven settings schema, inheritance, and validators.	FormBuilderFieldDefinition
formBuilderSettings	Legacy helper for registering a settings component for an existing field type. Prefer settings.schema on the field definition.	FormBuilderSettingsDefinition

Injection tokens

Token	Description	Type
FORM_BUILDER_ITEMS	Multi provider token for layout, static, or field-like palette items.	InjectionToken<FormBuilderItemDefinition[]>
FORM_BUILDER_FIELDS	Multi provider token for concrete field definitions available in the palette and renderer.	InjectionToken<FormBuilderFieldDefinition[]>
FORM_BUILDER_SETTINGS	Multi provider token for legacy settings components keyed by field or item type.	InjectionToken<FormBuilderSettingsDefinition[]>
FORM_BUILDER_UPLOAD_CALLBACK	Global upload handler used when no component-level uploadCallback input is supplied.	InjectionToken<FormBuilderUploadCallback>
FORM_BUILDER_SELECT_DATA_SOURCES	Multi provider token containing registered select data source definitions.	InjectionToken<FormBuilderSelectDataSourceDefinition[]>

FormBuilderSchema

Property	Description	Type
title	Optional schema title for your own storage, previews, or surrounding UI.	string
fields	Optional top-level fields that are not inside a section. Layout order is controlled by layout when present.	FormBuilderField[]
layout	Optional ordered list of top-level field and section ids. Missing items are appended automatically by the builder and renderer.	FormBuilderLayoutItem[]
flow	Optional presentation flow. Use mode steps with FormBuilderStep entries to render the same form as a multi-step flow.	FormBuilderFlow
sections	Required list of sections. A schema may use an empty array when all fields live at the top level.	FormBuilderSection[]

FormBuilderFlow

Property	Description	Type
mode	single renders the flat layout. steps renders flow.steps through NgStarter Stepper.	'single' \| 'steps'
steps	Ordered step definitions. Each step references existing top-level fields or sections through items. Can be stored in schema.flow or passed to FormRenderer through its flow input.	FormBuilderStep[]

FormBuilderStep

Property	Description	Type
id	Stable step id used by builder canvas, Layers, and drag/drop.	string
title	Step label shown in Layers, builder canvas, and the runtime stepper.	string
description	Optional helper text shown in the builder canvas and renderer.	string
optional	Marks the step as optional in the runtime stepper.	boolean
items	Ordered references to top-level fields or sections displayed in this step.	FormBuilderLayoutItem[]

FormBuilderField

Property	Description	Type
id	Stable unique id used by drag/drop layout and field selection.	string
name	Reactive form control name and saved value key. The builder inspector shows the resulting field path for nested fields, for example invoice_items.item_description.	string
type	Field type matched to a FormBuilderFieldDefinition.	string
kind	Optional item kind. Defaults to field; layout and static alter rendering and form control creation.	FormBuilderItemKind
label	Visible label used by the builder canvas, renderer, and default settings.	string
placeholder	Placeholder passed to input-like default renderers.	string
hint	Helper text shown by supported renderers.	string
defaultValue	Initial value used when the renderer creates a FormControl.	any
multiple	Enables multi-value behavior for select and upload-like fields.	boolean
clearable	Enables clear action for supported select-like controls.	boolean
required	Adds required validation and updates built-in settings state.	boolean
disabled	Creates the runtime control in a disabled state.	boolean
readonly	Marks the field readonly for renderers that support readonly display.	boolean
width	Grid width from 1 to 12 columns.	FormBuilderFieldWidth
options	Choice options for select, radio, and other option-based renderers.	FormBuilderOption[]
optionsSource	Select field source mode. Use static for textarea-defined options or dataSource for registered async data sources.	'static' \| 'dataSource'
dataSource	Registered select data source id used when optionsSource is dataSource.	string
dataSourceOptions	Optional runtime options for a select data source such as page size, search debounce, and minimum search length.	FormBuilderSelectDataSourceOptions
validation	Declarative validation rules used when no custom validators factory is supplied.	FormBuilderValidationRule[]
settings	Custom configuration bag for renderer-specific and settings-schema values.	Record<string, any>
children	Nested child fields for layout containers such as group and repeater.	FormBuilderField[]

FormBuilderSelectDataSourceDefinition

Property	Description	Type
id	Stable id saved on FormBuilderField.dataSource.	string
name	Human-readable name shown in the select field inspector.	string
dataSource	Async SelectDataSource function used by the runtime select renderer.	SelectDataSource
optionContentComponent	Optional Angular component used to render async option rows in form-builder select fields.	Type<any>
valueComponent	Optional Angular component used to render selected async values in form-builder select fields.	Type<any>

FormBuilderSelectDataSourceOptions

Property	Description	Type
pageSize	Async page size passed to the select data source. Form Builder select defaults to 20.	number
searchable	Whether the runtime select search input is enabled. Form Builder data source selects enable search by default.	boolean
searchDebounce	Debounce in milliseconds before remote search requests. Defaults to 250.	number
minSearchLength	Minimum typed search length before remote search. Form Builder select defaults to 1.	number
loadOnOpen	Whether to load the first async page when the select opens. Defaults to true.	boolean

Built-in field types

Type	Description	Group
text	Single-line text input.	Basic
number	Native numeric input rendered with NgStarter field styling.	Basic
email	Email input with built-in email validator support.	Basic
hidden	Native input type="hidden" included in raw submitted values.	Basic
textarea	Multi-line text input.	Basic
select	Single or multiple option selection.	Choices
radio	Radio group backed by field options.	Choices
checkbox	Boolean checkbox field.	Choices
toggle	Boolean slide toggle field.	Choices
date	Single date input.	Date and time
time	Time input.	Date and time
date-range	Start and end date input.	Date and time
timezone-select	Timezone selector.	Date and time
upload	File upload control with optional upload callback.	Files
logo-upload	Single logo upload control with preview, format settings, max file size, and optional upload callback.	Files
currency	Numeric currency amount input.	Finance
currency-select	Currency selector.	Finance
country-select	Country selector.	Location
group	Layout container for nested child fields.	Layout
repeater	Layout container that renders child fields as a FormArray.	Layout
plain-text	Static text block with optional expression-based output.	Layout
spacer	Static vertical spacing block.	Layout

Field and item definitions

Property	Description	Type
type	Unique palette and renderer type. Schema fields use the same value.	string
label	Palette label shown to users.	string
kind	Controls whether the item is a form field, layout item, or static block.	FormBuilderItemKind
group	Palette group name. Use Layout for layout items.	string
icon	Icon name shown in the palette.	string
description	Optional palette helper text.	string
defaults	Partial field data applied when the item is inserted into a schema.	Partial<FormBuilderField>
renderer	Lazy component importer for a custom runtime field renderer.	FormBuilderComponentImporter
settings	Settings component importer or schema-driven settings configuration.	FormBuilderComponentImporter \| FormBuilderSettingsConfig
acceptsChildren	Allows nested fields in the builder canvas and renderer.	boolean
validators	Custom validator factory for fields of this type.	(field: FormBuilderField) => ValidatorFn[]

Settings inheritance

Value	Description	Type
field	Base settings for label, field id, hint, width, required, readonly, and disabled.	FormBuilderSettingsInheritance
input-field	Field settings plus placeholder for input-like controls.	FormBuilderSettingsInheritance
layout	Base layout settings for label, hint, and width.	FormBuilderSettingsInheritance
layout-container	Container layout settings for label and width.	FormBuilderSettingsInheritance
static	Static block settings for label and width.	FormBuilderSettingsInheritance
none	Use only the supplied settings schema.	FormBuilderSettingsInheritance