preact-signal-formly

Getting started

Install#

npm i @dmytromykhailiuk/preact-signal-formly @dmytromykhailiuk/preact-signal-hook-forms @preact/signals preact

Quick start#

Build a form component once at module scope, then feed it three writable signals.

import { signal } from "@preact/signals";
import { createFormlyFormBuilder, defineFields } from "@dmytromykhailiuk/preact-signal-formly";

// 1. Build once — register whatever you need, then build().
const FormlyForm = createFormlyFormBuilder().build<{ email: string; bio: string }>();

// 2. Three writable signals: model, config, formState.
const model = signal({ email: "", bio: "" });
const formState = signal(undefined);
const config = signal(
  defineFields([
    { key: "email", type: "input", props: { label: "Email", required: true } },
    { key: "bio", type: "textarea", props: { label: "Bio" } },
  ]),
);

export function App() {
  return (
    <FormlyForm
      model={model}
      config={config}
      formState={formState}
      formOptions={{ mode: "onBlur" }}
      onSubmit={(values) => console.log(values)}
    >
      <button type="submit">Send</button>
    </FormlyForm>
  );
}

The builder is separate from the component on purpose: build() takes an immutable snapshot of the registry, so a registration made afterwards can never change a form that is already running.

The signal rules#

Everything the API hands you is a signal, a callback, or a stable reference — never a plain value that changes. Three rules keep the zero-re-render promise intact when you write your own types:

1. Never read signal.value in a component body. That subscribes the component and causes a re-render. Unwrap only inside computed / useComputed / effect / useSignalEffect.
2. Pass signals straight to the DOM — disabled={disabledComputed}, <span>{label}</span>. Preact binds them without re-rendering the component.
3. Use <For> and <Show> from @preact/signals/utils for lists and conditionals, instead of mapping arrays and writing ternaries in JSX.

createFieldType(({ id, control, namePath, props, fieldState }) => {
  // Runs exactly once. Everything dynamic below is a signal.
  const placeholder = useComputed(() => props.value.placeholder ?? "");
  const invalid = useComputed(() => (fieldState.error.value ? "true" : "false"));
  return <input {...control.register(namePath)} id={id} placeholder={placeholder} aria-invalid={invalid} />;
});

Reference

The form component#

builder.build<Model>() returns a component. It owns the underlying form control, the two-way syncing, and the field tree.

Props#

formOptions#

Field config#

The three kinds#

A field is exactly one of three things, decided by which property it carries:

Keys compose into dot-paths automatically: a leaf city inside a group address is address.city; inside an array it becomes phones.0.number. A group with no key is purely a layout wrapper — it adds a <div> and no path segment.

Every option#

defaultValue#

defaultValue applies when the model has no value at that path — the model always wins. It is not just written into the field: it is registered as the control's default for that path, which means the field starts pristine (isDirty === false) and control.reset() restores it rather than clearing it.

It works on every kind of field, and on fields that only appear in the config later.

defineFields([
  // Leaf: a scalar.
  { key: "role", type: "select", defaultValue: "viewer", props: { options } },

  // Group: a whole object. Children it covers keep quiet; "last" still applies its own.
  {
    key: "user",
    defaultValue: { first: "Jane" },
    fieldGroup: [
      { key: "first", type: "input" },
      { key: "last", type: "input", defaultValue: "Doe" },
    ],
  },

  // Array: the initial rows, in place before the row list is built.
  {
    key: "phones",
    defaultValue: [{ number: "" }],
    fieldArray: { fieldGroup: [{ key: "number", type: "input" }] },
  },
]);

Expressions#

An expression makes part of a field config dynamic. All of them are evaluated inside computeds, so reading the model tracks it — the field updates without anything re-rendering.

Four forms#

expressions: {
  "props.label": "Static value",                          // 1. a plain value
  "props.max": someSignal,                                // 2. a signal
  "props.disabled": ({ model }) => !model.value.country,  // 3. a callback
  "props.hint": { $expr: "model.value.country" },         // 4. a string expression
}

A callback receives the expression context:

Keys#

String expressions#

A config that arrives from a backend is JSON, and JSON cannot carry a callback. So an expression may also be written as a string — the entire config below is JSON.parse-able, with no JavaScript in it:

{
  "key": "city",
  "type": "input",
  "hide": "!model.value.address.country",
  "expressions": {
    "props.disabled": { "$expr": "!model.value.address.country" },
    "props.placeholder": { "$expr": "model.value.address.country ? 'Enter a city' : 'Pick a country'" },
    "className": { "$expr": "model.value.compact ? 'row tight' : 'row'" }
  }
}

hide accepts a bare string: its target is a boolean, so a string there could never have been a meaningful static value. Everywhere else the string must be wrapped in { "$expr": "..." } — otherwise "props.label": "Name" would be parsed as code instead of staying the label it obviously is.

Grammar#

• Member access never throws. model.value.a.b.c with a missing a yields undefined, because a JSON author cannot be expected to write ?. at every step.
• A malformed expression throws, quoting the source and the position — that is a broken config, not a runtime state.
• Methods are matched by identity against the built-in prototypes, so an object in your own model that happens to have an includes property cannot be invoked through an expression.
• repeat, padStart and padEnd are excluded on purpose: with an untrusted expression they are a denial-of-service primitive.
• constructor, __proto__ and prototype cannot be read at all, including through a computed key.
• Parsed expressions are cached by source, so a string is parsed once no matter how often it is evaluated.

Validation#

Three layers#

All three report per field as signals, with resolved human-readable messages.

// 1. Built-in rules, expressed as props.
{ key: "age", type: "input", props: { type: "number", required: true, min: 18, max: 120 } }
{ key: "code", type: "input", props: { minLength: 4, maxLength: 8, pattern: /^[A-Z]+$/ } }

// 2. Validators registered on the builder, referenced by name.
builder.registerValidator("email", (value) => !value || value.includes("@"), "Invalid email");
{ key: "email", type: "input", validators: { validation: ["email"] } }

// 3. Inline validators. The key becomes the error type used for message lookup.
{
  key: "password",
  type: "input",
  validators: {
    strong: (value) => /[0-9]/.test(value) || "Needs a digit",
    matches: {
      expression: (value, model) => value === model.confirm,
      message: "Passwords do not match",
    },
  },
}

A validator receives (value, model, fieldConfig, abortSignal?) and returns true/undefined for valid, false for invalid (message resolved from the registry), or a string used directly as the message. Async validators are supported and get an AbortSignal that fires when a newer run supersedes them.

builder.registerValidator("uniqueSlug", async (value, _model, _field, signal) => {
  if (!value) return true;
  const res = await fetch(`/api/slug/${value}`, { signal });
  return (await res.json()).free || "That slug is taken";
});

Rules are read through getters that peek the current config, so editing props.min through a config replacement takes effect on the next validation run — the field does not need to re-register.

Messages#

Precedence, first match wins:

1. the field's validation.messages[errorType]
2. the inline validator entry's own message
3. a message registered with registerValidationMessage(errorType, …)
4. the default message given to registerValidator
5. the string the validator returned
6. the error type itself, as a last resort

Any message may be a function of (error, fieldConfig):

builder.registerValidationMessage("minLength", (_error, field) =>
  `${field.props?.label ?? "This field"} needs at least ${field.props?.minLength} characters`,
);

// Or for one field only:
{ key: "pin", type: "input", props: { minLength: 4 }, validation: { messages: { minLength: "4 digits" } } }

Defaults shipped

When validation runs#

mode governs behaviour before the first submit. reValidateMode takes over once the form has been submitted or while the field is showing an error — that pairing is what lets a form stay quiet until submit and then turn responsive per keystroke.

reValidateMode is "onChange" (default), "onBlur" or "onSubmit". With mode: "all" it changes nothing on its own — it only matters once you loosen mode.

Set it for the whole form through formOptions, and override it per field in the config. A field can be both stricter and looser than its form:

<FormlyForm … formOptions={{ mode: "onBlur", reValidateMode: "onChange" }} />

defineFields([
  // Validates on every keystroke, though the form is "onBlur".
  { key: "slug", type: "input", validation: { mode: "onChange" } },
  // Stays quiet until submit, though the form is not.
  { key: "notes", type: "textarea", validation: { mode: "onSubmit" } },
  // Only the re-validation behaviour differs.
  { key: "email", type: "input", validation: { reValidateMode: "onBlur" } },
]);

Builder API#

Every method returns the builder, so registrations chain. build() snapshots them.

const builder = createFormlyFormBuilder()
  .registerType("rating", RatingType, { wrappers: ["field"], defaultProps: { max: 5 } })
  .registerType("stars", StarsType, { extends: "rating" })   // inherits wrappers + defaultProps
  .registerArrayType("phones", PhonesArray)
  .registerWrapper("highlight", HighlightWrapper)
  .registerLazyType("editor", () => import("./types/Editor"), { wrappers: ["field"] })
  .registerLazyArrayType("gallery", () => import("./types/Gallery"))
  .registerLazyWrapper("card", () => import("./wrappers/Card"))
  .registerValidator("email", emailValidator, "Please enter a valid email")
  .registerValidationMessage("required", "Don't leave this empty")
  .registerExtension("autoLabel", autoLabelExtension);

const FormlyForm = builder.build<Model>();

Lazy types & wrappers#

A registry usually outlives any single form: a rich text editor, a date picker, a map picker are all registered up front, and most forms use none of them. registerLazyType, registerLazyArrayType and registerLazyWrapper take a loader — a function returning a dynamic import() — so the component travels in its own chunk, fetched only when a field that uses it first renders.

const builder = createFormlyFormBuilder()
  .registerLazyType("rating", () => import("./types/Rating"), {
    wrappers: ["field"],
    defaultProps: { max: 5 },
  })
  .registerLazyArrayType("phones", () => import("./types/PhonesArray"))
  .registerLazyWrapper("card", () => import("./wrappers/Card"));

// Used in a config exactly like an eagerly registered name:
const fields = [{ key: "score", type: "rating" }];

builder.registerLazyWrapper("card", () => import("./wrappers/Card"), {
  errorFallback: (error) => (
    <p class="load-error">Could not load this field: {String(error)}</p>
  ),
});

Built-ins#

Types

All of them are exported (InputType, TextareaType, SelectType, CheckboxType, RadioType) so you can compose or re-register them.

The props built-in types understand

Anything else you put in props is yours — FormlyBaseProps has an index signature.

The "field" wrapper

The default wrapper for every built-in type. Renders a <div> with ctx.className (falling back to formly-field), a <label for> with a * marker when required, the control, an optional description, and the error message in a role="alert" element with class formly-error. It ships unstyled — the class names are the styling hooks.

Writing a field type#

A field type is a Preact component whose props are the field context. createFieldType is an identity helper that exists purely to give you the typing and an optional display name.

Binding the input#

You receive control and namePath and bind the input yourself, exactly as you would with the base library outside of formly. Two ways:

Uncontrolled — spread register

import { useComputed } from "@preact/signals";
import { createFieldType } from "@dmytromykhailiuk/preact-signal-formly";

const Text = createFieldType<{ placeholder?: string }>(
  ({ control, namePath, props, errorMessage, id }) => {
    const placeholder = useComputed(() => props.value.placeholder ?? "");
    return (
      <div>
        <input {...control.register(namePath)} id={id} placeholder={placeholder} />
        <span role="alert">{errorMessage}</span>
      </div>
    );
  },
  "Text",
);

Controlled — Controller or useController

For widgets with no DOM input of their own:

import { Controller } from "@dmytromykhailiuk/preact-signal-hook-forms";

const Rating = createFieldType<{ max?: number }>(({ control, namePath, props, id }) => {
  const max = useComputed(() => props.value.max ?? 5);
  return (
    <Controller
      control={control}
      name={namePath}
      render={({ field }) => (
        <div id={id}>
          {/* field.value is a signal; field.onChange/onBlur are callbacks */}
          <span>{field.value}</span> / <span>{max}</span>
          <button type="button" onClick={() => field.onChange((field.value.peek() ?? 0) + 1)}>+</button>
        </div>
      )}
    />
  );
});

Context reference#

Wrappers get all of the above plus children. Array types get all of it plus array and renderItems. Hooks get the base members only — no fieldState, no errorMessage.

Wrappers#

A wrapper decorates a field — label, error, layout. wrappers[0] is the outermost.

const Card = createWrapper(({ props, errorMessage, className, children, id }) => {
  const label = useComputed(() => props.value.label);
  const cls = useComputed(() => className.value ?? "card");
  return (
    <div class={cls}>
      <label for={id}>{label}</label>
      {children}
      <span class="formly-error">{errorMessage}</span>
    </div>
  );
}, "Card");

builder.registerWrapper("card", Card);
// then: { key: "email", type: "input", wrappers: ["card"] }

Array types#

An array type owns the layout and the controls for a repeating field. renderItems() renders the rows; array is the stable API from the base library.

const PhonesArray = createArrayType<{ number: string }>(({ array, renderItems, props }) => {
  const label = useComputed(() => props.value.label ?? "Items");
  return (
    <div>
      <label>{label}</label>
      {renderItems()}
      <button type="button" onClick={() => array.append({ number: "" })}>+ phone</button>
      <button type="button" onClick={() => array.remove(array.fields.peek().length - 1)}>− last</button>
    </div>
  );
});

builder.registerArrayType("phones", PhonesArray);

array carries fields (a signal of rows with stable ids), append, prepend, insert, remove, swap, move and replace. Without a registered array type, the rows render bare from the template.

Groups & arrays#

defineFields([
  // Keyed group → paths become address.country, address.city
  {
    key: "address",
    fieldGroupClassName: "row",
    fieldGroup: [
      { key: "country", type: "select", props: { label: "Country", options } },
      { key: "city", type: "input", props: { label: "City" }, hide: "!model.value.address.country" },
    ],
  },

  // Keyless group → pure layout, no path segment
  {
    fieldGroupClassName: "row",
    fieldGroup: [
      { key: "first", type: "input" },
      { key: "last", type: "input" },
    ],
  },

  // Array → phones.0.number, phones.1.number …
  {
    key: "phones",
    type: "phones",                       // a registered array type (optional)
    props: { label: "Phones", required: true },
    defaultValue: [{ number: "" }],
    fieldArray: {
      className: "phones-item",
      fieldGroup: [{ key: "number", type: "input", props: { minLength: 5 } }],
    },
  },

  // Array with a per-row template
  {
    key: "steps",
    fieldArray: (index) => ({
      fieldGroup: [{ key: "name", type: "input", props: { label: `Step ${index + 1}` } }],
    }),
  },
]);

Array-level rules attach to the array node itself, so props.required or props.minLength on an array field validates the list rather than an item. Rows remount on every structural change — the base library drops and recreates child nodes on append/remove/move, so a controller must never survive one.

Field hooks#

onInit runs once after the field mounts and may return a cleanup function. onDestroy runs when the field unmounts — including when it is removed from the config, which is exactly when the config no longer describes it.

{
  key: "country",
  type: "select",
  hooks: {
    onInit: ({ control, namePath, props }) => {
      const dispose = effect(() => {
        // Runs whenever the value changes — no re-render involved.
        console.log(namePath, control.watch(namePath).value);
      });
      return dispose;              // cleanup, called on unmount
    },
    onDestroy: ({ namePath }) => console.log("gone:", namePath),
  },
}

The context is the base field context — control, namePath, props, className, config, formState, id.

Extensions#

An extension mutates the config draft during resolution — Formly semantics, for cross-cutting conventions you do not want to repeat in every field. The draft is a private clone, so the config object you passed is never touched.

Order per field: prePopulate → type defaults merge → onPopulate → postPopulate.

const autoLabel = createExtension({
  prePopulate: (field) => {
    if (field.key && !field.props?.label) {
      const key = String(field.key);
      field.props = { ...field.props, label: key[0].toUpperCase() + key.slice(1) };
    }
  },
});

builder.registerExtension("autoLabel", autoLabel);

Extensions run inside a computed on every resolution, so they must be pure with respect to their input — the same draft in, the same draft out.

TypeScript#

defineFields narrows props by the registered type name. Pass BuilderTypes<typeof builder> to pick up your own registrations:

import { defineFields, type BuilderTypes } from "@dmytromykhailiuk/preact-signal-formly";

interface RatingProps { max: number; [key: string]: any }

const builder = createFormlyFormBuilder().registerType<"rating", RatingProps>("rating", Rating);

const fields = defineFields<BuilderTypes<typeof builder>>([
  { key: "score", type: "rating", props: { max: 5 } },   // `max` is checked
  { key: "name", type: "input", props: { label: "Name" } },
]);

Without a type parameter, defineFields uses the built-in types. Unregistered names and array fields fall back to the loose FormlyFieldConfig, so nothing is ever blocked by the typing — it only narrows what it can.

Field types take their own generics: createFieldType<Props, Model>, createArrayType<Item>, createValidator<Value, Model>.

Escape hatches#

let control: FormControl<Model>;

<FormlyForm … controlRef={(c) => (control = c)} />

await control.trigger();                       // validate everything
await control.trigger("address.city");         // …or one path
control.reset();                               // back to the defaults, pristine
control.setError("email", { type: "server", message: "Already taken" });
control.setFocus("email");
control.formState.isValid.value;               // signals, all of them
control.formState.dirtyFields.value;

RegistryContext is exported too, for building your own rendering on top of the registry a builder produced.

Exports#

Values

createFormlyFormBuilder · defineFields · createFieldType · createWrapper · createArrayType · createValidator · createExtension · registerBuiltIns · defaultValidationMessages · InputType · TextareaType · SelectType · CheckboxType · RadioType · FieldWrapper · RegistryContext

Types

FormlyFieldConfig · FormlyBaseProps · FormlyExpression · FormlyExpressions · FormlyExpressionKey · FormlyExprRef · FormlyExpressionCtx · FormlyFieldContext · FormlyFieldBaseContext · FormlyHookContext · WrapperContext · FieldArrayContext · FieldTypeComponent · WrapperComponent · ArrayTypeComponent · FormlyFormProps · FormlyFormComponent · FormlyFormBuilder · FormlyBuilderOptions · FormlyExtension · FormlyFieldHooks · FormlySelectOption · FormlySharedState · FormlyValidatorFn · FormlyValidatorEntry · FormlyValidatorsConfig · FormlyValidationMessage · TypeRegistrationOptions · LazyTypeRegistrationOptions · LazyRegistrationOptions · LazyComponentLoader · LazyComponentModule · BuilderTypes · TypedFieldConfig · BuiltInTypes · FormlyRegistry

Re-exported from the base library so you can type them without importing it: ValidationMode · ReValidateMode · UseFormOptions.