SDK Types: Forms

description

string | null

No

Optional form description, displayed above the form fields.<br>null if not set. Max 1000 characters.<br>Can be used as introductory text or instructions for the user.

honeypotEnabled

boolean

Yes

Whether honeypot spam protection is enabled for this form.<br><br>When true, your frontend must render a hidden honeypot field<br>(invisible to humans, filled by bots). The SDK handles this automatically<br>via lynkow.forms.submit(), but if you submit manually, include an empty<br>hidden field named per the spam protection API specification.<br><br>undefined or false means honeypot is not active.

id

string

No

Unique form identifier (UUID v4).

locale

string

Yes

BCP 47 locale code of this form (e.g. 'en', 'fr').<br>undefined if the form is not locale-specific (shared across all locales).

name

string

No

Form display name (e.g. 'Contact Us', 'Newsletter Signup'). Max 255 characters.

recaptchaEnabled

boolean

Yes

Whether Google reCAPTCHA v3 is enabled for this form.<br><br>When true, your frontend must:<br>1. Load the reCAPTCHA script using recaptchaSiteKey<br>2. Execute grecaptcha.execute() before submission<br>3. Include the reCAPTCHA token in the submission payload<br><br>The SDK handles this automatically if you use lynkow.forms.submit().<br>Cannot be combined with honeypot; only one spam protection method is active.<br><br>undefined or false means reCAPTCHA is not active.

recaptchaSiteKey

string | null

Yes

Google reCAPTCHA v3 public site key, needed to render the reCAPTCHA widget.<br>Only present when recaptchaEnabled is true.<br>null or undefined when reCAPTCHA is not configured.<br><br>Pass this to grecaptcha.render() or the sitekey parameter in the reCAPTCHA script URL.<br>The secret key is never exposed; it stays server-side.

schema

FormSchema

No

Schema describing the form's fields, layout, behavior settings, and<br>conditional logic. Iterate schema.fields to render the form.

slug

string

No

URL-friendly slug, unique within the site.<br>Lowercase, hyphenated (e.g. 'contact-us'). Max 255 characters.<br>Used to fetch the form: GET /public/{siteId}/forms/{slug}.<br>Also used as the submission endpoint: POST /public/{siteId}/forms/{slug}/submissions.

status

"active"

No

Form status. Always 'active' via the public API.<br>Draft, closed, and archived forms are never returned by public endpoints.

action

"show" | "hide" | "require" | "skip_to_page"

No

Effect applied when the condition matches:<br>- 'show' / 'hide': toggle visibility of the target field<br>- 'require': mark the target field required<br>- 'skip_to_page': jump to the page identified by targetPage

field

string

No

The FormField.id of the field whose value triggers this condition.

operator

"equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than" | "is_empty" | "is_not_empty"

No

Comparison operator applied to the referenced field's current value.

targetPage

number

Yes

Target page index for skip_to_page actions.<br>Ignored for other actions.

value

unknown

Yes

Value compared against the referenced field. Type depends on the field<br>type: string for text fields, number for number fields, boolean for<br>checkboxes. undefined for is_empty / is_not_empty.

conditions

FormCondition[]

Yes

Per-field conditional logic. When present, the field is only rendered or<br>required based on the values of earlier fields. Conditions defined here<br>are scoped to this field; cross-field rules live in FormSchema.conditions.

defaultValue

string | number | boolean

Yes

Pre-filled default value for the field.<br>Type depends on the field type: string for text fields, number for number fields,<br>boolean for checkbox (single toggle mode).<br>undefined if no default is set. The field starts empty.

description

string

Yes

Help text displayed below the input to guide the user.<br>Max 500 characters. undefined if not configured.<br>Render as a small description below the field (e.g. <small> or aria-describedby).

id

string

No

Field identifier, used as the key in submission data.<br>Auto-generated by the admin (e.g. 'field_1764776796820'), unique within<br>the form. This is the key you must use in FormSubmitData when calling<br>forms.submit().

label

string

No

Human-readable label displayed above or beside the input.<br>Max 255 characters. Always present. Use this as the <label> text.

options

FormFieldOption[]

Yes

Selectable options for select, radio, and checkbox field types.<br>undefined for field types that don't use options (text, email, number, etc.).<br>For checkbox with options, render as a checkbox group (multiple selections).<br>For checkbox without options, render as a single boolean toggle.

phoneOptions

FormFieldPhoneOptions

Yes

Configuration for tel (phone) fields.<br>undefined for non-phone field types.

placeholder

string

Yes

Placeholder text shown inside the input when empty.<br>Max 255 characters. undefined if not configured.<br>Use as the HTML placeholder attribute.

required

boolean

Yes

Whether this field must be filled before submission.<br>When true, the server will reject submissions with this field empty.<br>Render a required indicator (e.g. *) and set the HTML required attribute.<br>undefined is treated as false.

type

FormFieldType

No

HTML input type for this field.<br>Determines the rendered input element and applicable validation rules.

validation

FormFieldValidation

Yes

Validation rules applied to this field's value.<br>undefined if no extra validation beyond required is configured.<br>Rules are enforced server-side; client-side validation is optional but recommended for UX.

width

"full" | "half" | "third"

Yes

Layout width hint for responsive form layouts:<br>- 'full': spans the entire form width (100%)<br>- 'half': spans half the form width (50%); place two half fields side by side<br>- 'third': spans one third of the form width (33%); place three third fields in a row<br><br>undefined defaults to 'full'.

label

string

No

Human-readable label displayed to the user in the form UI.<br>May differ from value (e.g. label: 'United States', value: 'US').

value

string

No

The value sent in the form submission data.<br>This is the machine-readable identifier stored in the database.<br>Must be unique within the field's options array.

defaultCountryCode

string

No

Default country code (e.g. '+33', '+1').

showCountryCode

boolean

No

Whether the country-code selector is rendered next to the phone input.

accept

string

Yes

Accepted MIME types or extensions for file fields (e.g. 'image/*,.pdf').<br>Mirrors the HTML accept attribute. Ignored for non-file fields.

max

number

Yes

Maximum numeric value (inclusive).<br>Only applicable to number field type.<br>Ignored for text fields. Use maxLength instead.

maxLength

number

Yes

Maximum character length for text input.<br>Applicable to text, email, textarea, url, tel field types.<br>Ignored for non-text fields.

maxSize

number

Yes

Maximum file size in bytes for file fields.<br>Ignored for non-file fields.

message

string

Yes

Custom error message displayed when validation fails.<br>undefined means the browser/framework default message is used.<br>Supports the field's locale if i18n is configured.

min

number

Yes

Minimum numeric value (inclusive).<br>Only applicable to number field type.<br>Ignored for text fields. Use minLength instead.

minLength

number

Yes

Minimum character length for text input.<br>Applicable to text, email, textarea, url, tel field types.<br>Ignored for non-text fields (number, select, checkbox, etc.).

pattern

string

Yes

Regular expression pattern for custom validation (e.g. '^[A-Z]{2}\\d{4}$').<br>Validated as a JavaScript RegExp. Do not include delimiters (no /pattern/).<br>Applicable to any text-based field type.

description

string

Yes

Page description displayed below the title.<br>undefined if not configured.

fields

string[]

No

Ordered list of FormField.id values that belong to this page.<br>Each id must reference a field in FormSchema.fields.

title

string

Yes

Page title displayed at the top of the page.<br>undefined if not configured.

conditions

FormCondition[]

No

Cross-field conditional logic rules. Each rule references a field by id,<br>compares its value, and applies an action (show/hide/require/skip).

fields

FormField[]

No

Ordered array of field definitions that make up the form.<br>Render in order to build the form UI.

pages

FormPage[]

Yes

Page definitions for multi-page forms.<br>undefined for single-page forms.

settings

FormSchemaSettings

No

Behavior settings (submit label, success message, redirect, progress bar).

closedMessage

string

Yes

Message displayed when the form is closed (no longer accepting submissions).<br>undefined falls back to a default message.

redirectUrl

string

Yes

URL to redirect the user to after successful submission.<br>Must be a valid URL. When set, takes precedence over successMessage.<br>undefined means show successMessage inline instead.

requireAuth

boolean

Yes

Whether the form requires the visitor to be authenticated.<br>Enforced server-side. undefined is treated as false.

showProgressBar

boolean

Yes

Whether to render a progress bar for multi-page forms.<br>undefined is treated as false.

submitLabel

string

Yes

Text displayed on the submit button (e.g. 'Send', 'Subscribe').<br>undefined falls back to a default label rendered by the host application.

successMessage

string

Yes

Success message displayed after a successful submission.<br>Shown inline on the page. Ignored if redirectUrl is set.<br>undefined falls back to a default message.