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

number

No

Unique numeric form ID. Auto-incremented.

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

FormField[]

No

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

settings

FormSettings

No

Form behavior settings (submit button text, success message, redirect).

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/forms/:slug.<br>Also used as the submission endpoint: POST /public/forms/:slug/submit.

status

"active"

No

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

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.

helpText

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).

label

string

No

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

name

string

No

Field identifier, used as the key in submission data.<br>Unique within the form. Lowercase, alphanumeric with underscores or hyphens<br>(e.g. 'first_name', 'email'). Max 100 characters.<br>This is the key you use in FormSubmitData when submitting.

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.

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

No

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.

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.

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.

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.

doubleOptIn

boolean

Yes

Whether double opt-in email confirmation is enabled.<br>When true, the form sends a confirmation email to the user before<br>recording the submission as confirmed. Useful for newsletter signups.<br>undefined or false means submissions are recorded immediately.

redirectUrl

string

Yes

URL to redirect the user to after successful submission.<br>Max 500 characters. Must be a valid URL (e.g. 'https://example.com/thank-you').<br>When set, takes precedence over successMessage — the user is navigated away immediately.<br>undefined means show successMessage inline instead.

submitLabel

string

No

Text displayed on the submit button (e.g. 'Send', 'Subscribe', 'Submit').<br>Max 100 characters. Always present.

successMessage

string

No

Success message displayed after a successful submission.<br>Max 1000 characters. Shown inline on the page.<br><br>Ignored if redirectUrl is set — the user is redirected instead of seeing this message.