Form — wd-form

Category: Form · Tag: wd-formBack to: Components overviewRelated: Forms module — where you build the form, its fields, validation, rules, and submit behaviour.

---

What it does

Embeds a form you built in the Forms module into a page, layout, or shared element. The component is a full schema-driven form engine: it renders the form's fields, runs validation and conditional rules (shouldDisplay / shouldEnable), shows a submit spinner, and either redirects or emits a submission on submit.

Build the form first. The fields, validators, submit action, and destination all come from the form's definition in the Forms module — this component just renders that form. Read the Forms guide for the field types, validation, rules, and submission handling.

---

Adding it & its settings

Add Component → Form → Form.

Basic Settings (all components): #id, Classes, Inline Style. Set an #id if you'll style with ::part().

Form Settings:

Setting	Type	Effect
Form	picker (by reference)	Choose which form (from the Forms module) to embed. Everything else — fields, validation, submit action, destination — comes from that form's definition.

---

Content & slots

The fields are generated from the form definition — you don't write them as child HTML. But the component has two slots, and one of them you're expected to fill:

Slot	Purpose
default (unnamed)	Your submit button (and any other trailing content). The component does not render a submit button — you supply it. It's placed after the last field, spanning the full width of the fields grid.
spinner (named)	Optional custom content for the submit overlay shown while the form is submitting (defaults to "loading…").

The submit button (important)

The Forms module has no submit button of its own — the button is author-supplied slotted content. Because the button lives in the light DOM (it's your markup, not shadow DOM), two things follow:

1. You wire it to submit yourself. A bare type="submit" won't submit the form — the button is slotted into the component's internal <form>, so it isn't that form's owner and no native submit fires. Instead, call the component's submit() method, e.g. from the button's click event (an Element Event → click in the builder):

   <wd-form id="signup" component-settings='…'>
     <button type="submit">Sign up</button>
   </wd-form>

   submit() validates all fields — marking them touched so every error message appears — and then either redirects to the destination page or emits formSubmitted (see the Forms module). If the form is invalid it rejects and sends nothing.

   The spinner is yours to control. submit() does not show it — call toggleSpinner() around your submit. The recommended wiring, as a page/layout script, shows the spinner only once the form is actually valid (so an invalid click never flashes it):

   const form = document.querySelector('#signup');
   const button = document.querySelector('#signup-submit');
   
   // wd-form emits formUpdated on every change/blur with the form's current validity.
   let isValid = false;
   form.addEventListener('formUpdated', (event) => { isValid = event.detail.isValid; });
   
   button.addEventListener('click', async () => {
     if (isValid) { await form.toggleSpinner(true); }
   
     try {
       await form.submit();          // re-validates; on failure it shows every error and rejects
     } catch (error) {
       await form.toggleSpinner(false);
     }
   });

   In a shared element (which has no script block) put the same handler body in the button's click element-event instead.

   For a redirect form, submit() navigates away and never settles — the spinner simply stays up through the navigation. For an emit form, whatever handles formSubmitted should turn the spinner off when its request finishes.

2. You style it with normal page CSS — not ::part() or the --form-* variables, which only reach the shadow-DOM internals. Ordinary selectors (#signup button { … }) apply directly.

Controlling placement. The slot sits full-width after the last field, so the button stretches across the grid. To align or size it, wrap it in a container and lay that out (e.g. display: flex; justify-content: center):

<wd-form id="signup" component-settings='…'>
  <div class="form-actions">
    <button type="submit" id="signup-submit">Sign up</button>
  </div>
</wd-form>

#signup .form-actions { display: flex; justify-content: center; margin-block-start: 1.3rem; }

---

Styling

The form has a large, fully-themeable surface. Style it from a page/layout CSS block using the CSS variables below (grouped by area and by field type), and use ::part() to reach the form wrapper.

::part()

Part	Element
form-<id>	The form wrapper.

wd-form::part(form-signup) { max-width: 640px; margin-inline: auto; }

CSS variables

There are 244 variables. They share a consistent naming scheme: --form-* for the form itself, --form-field-control-* for the shared input control (used by text/email/number/etc.), --form-field-<type>-* for a specific field type, --form-legend-* for section headings, and --form-spinner-* for the submit overlay. Defaults shown in the second column.

Form spacing (8)

Variable	Default
--form-field-padding-bottom	0px
--form-field-padding-inline-end	0px
--form-field-padding-inline-start	0px
--form-field-padding-top	0px
--form-padding-bottom	40px
--form-padding-left	20px
--form-padding-right	20px
--form-padding-top	40px

Fields container (2)

Variable	Default
--form-fields-grid-x-gap	16px
--form-fields-grid-y-gap	24px

Field wrapper (layout) (6)

Variable	Default
--form-field-align-items	flex-start
--form-field-display	flex
--form-field-flex-direction	column
--form-field-font-family	sans-serif
--form-field-gap	4px
--form-field-justify-content	flex-start

Field control — shared: inputs, borders, focus, valid/invalid, label, error (41)

Variable	Default
--form-field-control-bg-color	#fff
--form-field-control-border-bottom-left-radius	0.5rem
--form-field-control-border-bottom-right-radius	0.5rem
--form-field-control-border-color	1px solid #ced4da
--form-field-control-border-top-left-radius	0.5rem
--form-field-control-border-top-right-radius	0.5rem
--form-field-control-error-color	#dc3545
--form-field-control-error-font-family	sans-serif
--form-field-control-error-font-size	12px
--form-field-control-error-font-weight	400
--form-field-control-error-margin-top	0px
--form-field-control-focus-bg-color	#fff
--form-field-control-focus-border-color	#86b7fe
--form-field-control-focus-label-color	#5b89ce
--form-field-control-font-size	14px
--form-field-control-height	48px
--form-field-control-invalid-bg-color	rgba(255, 175, 200, 0.50)
--form-field-control-invalid-border-color	#dc3545
--form-field-control-invalid-label-color	#dc3545
--form-field-control-invalid-text-color	#463333
--form-field-control-label-bg-color	transparent
--form-field-control-label-bottom	auto
--form-field-control-label-color	#7b8895
--form-field-control-label-font-family	sans-serif
--form-field-control-label-font-size	14px
--form-field-control-label-font-weight	400
--form-field-control-label-left	auto
--form-field-control-label-order	1
--form-field-control-label-padding	0
--form-field-control-label-position	static
--form-field-control-label-right	auto
--form-field-control-label-top	auto
--form-field-control-max-width	100%
--form-field-control-order	2
--form-field-control-padding	0 12px
--form-field-control-text-color	#495057
--form-field-control-valid-bg-color	#fff
--form-field-control-valid-border-color	#ced4da
--form-field-control-valid-label-color	#7b8895
--form-field-control-valid-text-color	#495057
--form-field-control-width	100%

Checkbox field (27)

Variable	Default
--form-field-checkbox-checked-content-label-color	#212529
--form-field-checkbox-checked-content-paragraph-color	#6c757d
--form-field-checkbox-content-gap	0.5rem
--form-field-checkbox-content-label-color	#6c757d
--form-field-checkbox-content-label-font-family	sans-serif
--form-field-checkbox-content-label-font-size	1rem
--form-field-checkbox-content-label-font-weight	500
--form-field-checkbox-content-order	2
--form-field-checkbox-content-padding	4px 0 0
--form-field-checkbox-content-paragraph-color	#6c757d
--form-field-checkbox-content-paragraph-font-family	sans-serif
--form-field-checkbox-content-paragraph-font-size	0.875rem
--form-field-checkbox-content-paragraph-font-weight	300
--form-field-checkbox-content-paragraph-line-height	1.3
--form-field-checkbox-control-bg-color	#fff
--form-field-checkbox-control-border-color	#ced4da
--form-field-checkbox-control-border-radius	0.25rem
--form-field-checkbox-control-checked-border-color	purple
--form-field-checkbox-control-checkmark-bg-color	rgba(13, 109, 253, 0)
--form-field-checkbox-control-checkmark-border-radius	0.125rem
--form-field-checkbox-control-checkmark-checked-bg-color	purple
--form-field-checkbox-control-checkmark-checked-size	19px
--form-field-checkbox-control-checkmark-size	13px
--form-field-checkbox-control-size	21px
--form-field-checkbox-gap	12px
--form-field-checkbox-justify-content	flex-start
--form-field-checkbox-label-order	1

Radio field (43)

Variable	Default
--form-field-radio-background	#ccc
--form-field-radio-border-color	#ccc
--form-field-radio-border-radius	21px
--form-field-radio-checked-bg-color	#007bff
--form-field-radio-checked-border-color	#007bff
--form-field-radio-checked-content-label-color	#212529
--form-field-radio-checked-content-paragraph-color	#6c757d
--form-field-radio-checked-heading-color	#212529
--form-field-radio-content-gap	0.5rem
--form-field-radio-content-label-color	#6c757d
--form-field-radio-content-label-font-family	sans-serif
--form-field-radio-content-label-font-size	1rem
--form-field-radio-content-label-font-weight	500
--form-field-radio-content-order	2
--form-field-radio-content-padding	4px 0 0
--form-field-radio-content-paragraph-color	#6c757d
--form-field-radio-content-paragraph-font-family	sans-serif
--form-field-radio-content-paragraph-font-size	0.875rem
--form-field-radio-content-paragraph-font-weight	300
--form-field-radio-content-paragraph-line-height	1.3
--form-field-radio-control-bg-color	#ced4da
--form-field-radio-control-border-color	transparent
--form-field-radio-control-border-radius	21px
--form-field-radio-control-checked-bg-color	purple
--form-field-radio-control-checked-border-color	transparent
--form-field-radio-control-height	21px
--form-field-radio-control-switcher-bg-color	#fff
--form-field-radio-control-switcher-border-radius	24px
--form-field-radio-control-switcher-height	20px
--form-field-radio-control-switcher-width	20px
--form-field-radio-control-width	21px
--form-field-radio-description-color	#6c757d
--form-field-radio-description-font-family	sans-serif
--form-field-radio-description-font-size	14px
--form-field-radio-description-font-weight	400
--form-field-radio-gap	12px
--form-field-radio-heading-color	#6c757d
--form-field-radio-heading-font-family	sans-serif
--form-field-radio-heading-font-size	14px
--form-field-radio-heading-font-weight	600
--form-field-radio-justify-content	flex-start
--form-field-radio-label-order	1
--form-field-radio-size	21px

Toggle field (29)

Variable	Default
--form-field-toggle-checked-content-label-color	#212529
--form-field-toggle-checked-content-paragraph-color	#6c757d
--form-field-toggle-content-gap	0.5rem
--form-field-toggle-content-label-color	#6c757d
--form-field-toggle-content-label-font-family	sans-serif
--form-field-toggle-content-label-font-size	1rem
--form-field-toggle-content-label-font-weight	500
--form-field-toggle-content-order	2
--form-field-toggle-content-padding	4px 0 0
--form-field-toggle-content-paragraph-color	#6c757d
--form-field-toggle-content-paragraph-font-family	sans-serif
--form-field-toggle-content-paragraph-font-size	0.875rem
--form-field-toggle-content-paragraph-font-weight	300
--form-field-toggle-content-paragraph-line-height	1.3
--form-field-toggle-control-bg-color	#ced4da
--form-field-toggle-control-border-color	transparent
--form-field-toggle-control-border-radius	24px
--form-field-toggle-control-checked-bg-color	purple
--form-field-toggle-control-checked-border-color	transparent
--form-field-toggle-control-height	24px
--form-field-toggle-control-switcher-bg-color	#fff
--form-field-toggle-control-switcher-border-radius	24px
--form-field-toggle-control-switcher-box-shadow	0 1px 3px rgba(0, 0, 0, 0.6)
--form-field-toggle-control-switcher-height	20px
--form-field-toggle-control-switcher-width	20px
--form-field-toggle-control-width	34px
--form-field-toggle-gap	12px
--form-field-toggle-justify-content	flex-start
--form-field-toggle-label-order	1

Typeahead field (9)

Variable	Default
--form-field-typeahead-control-dropdown-bg-color	#fff
--form-field-typeahead-control-dropdown-border	1px solid #ddd
--form-field-typeahead-control-dropdown-border-radius	6px
--form-field-typeahead-control-dropdown-box-shadow	0 6px 18px rgba(0, 0, 0, 0.15)
--form-field-typeahead-control-dropdown-item-color	#212529
--form-field-typeahead-control-dropdown-item-font-size	14px
--form-field-typeahead-control-dropdown-item-hover-bg-color	#f2f2f2
--form-field-typeahead-control-dropdown-item-padding	10px 12px
--form-field-typeahead-control-dropdown-max-height	260px

File field (16)

Variable	Default
--form-field-file-control-padding	8px 8px
--form-field-file-control-selector-bg-color	purple
--form-field-file-control-selector-border-bottom	none
--form-field-file-control-selector-border-left	none
--form-field-file-control-selector-border-radius	0.375rem
--form-field-file-control-selector-border-right	none
--form-field-file-control-selector-border-top	none
--form-field-file-control-selector-color	white
--form-field-file-control-selector-font-size	14px
--form-field-file-control-selector-height	32px
--form-field-file-control-selector-hover-bg-color	rgb(96, 0, 96)
--form-field-file-control-selector-margin-end	8px
--form-field-file-control-selector-padding	4px 12px
--form-field-file-control-selector-top	50%
--form-field-file-control-selector-transform	translateY(-50%)
--form-field-file-control-selector-width	25%

Number field (12)

Variable	Default
--form-field-number-control-button-bg-color	#e0e0e0
--form-field-number-control-button-border	none
--form-field-number-control-button-border-bottom-left-radius	0.5rem
--form-field-number-control-button-border-bottom-right-radius	0.5rem
--form-field-number-control-button-border-top-left-radius	0.5rem
--form-field-number-control-button-border-top-right-radius	0.5rem
--form-field-number-control-button-color	#333
--form-field-number-control-button-font-size	1rem
--form-field-number-control-button-font-weight	500
--form-field-number-control-button-height	48px
--form-field-number-control-button-padding	0
--form-field-number-control-button-width	32px

Textarea field (2)

Variable	Default
--form-field-textarea-control-height	96px
--form-field-textarea-control-padding	8px 12px

Phone field (6)

Variable	Default
--form-field-phone-control-country-font-size	0.875rem
--form-field-phone-control-country-width	25%
--form-field-phone-control-separator-br-color	#ccc
--form-field-phone-control-separator-height	50%
--form-field-phone-control-separator-top	50%
--form-field-phone-control-separator-width	1px

Legend / section heading (26)

Variable	Default
--form-legend-align-items	center
--form-legend-bg-color	transparent
--form-legend-border-bottom	1px solid #dee2e6
--form-legend-border-radius	none
--form-legend-border-top	1px solid #dee2e6
--form-legend-description-color	#6c757d
--form-legend-description-font-family	sans-serif
--form-legend-description-font-size	14px
--form-legend-description-font-weight	400
--form-legend-description-text-align	center
--form-legend-flex-direction	column
--form-legend-gap	4px
--form-legend-justify-content	center
--form-legend-margin-bottom	0
--form-legend-margin-left	0
--form-legend-margin-right	0
--form-legend-margin-top	0
--form-legend-padding-bottom	1rem
--form-legend-padding-left	0px
--form-legend-padding-right	0px
--form-legend-padding-top	1.5rem
--form-legend-title-color	#212529
--form-legend-title-font-family	sans-serif
--form-legend-title-font-size	18px
--form-legend-title-font-weight	600
--form-legend-title-text-align	center

Submit spinner (17)

Variable	Default
--form-spinner-align-items	center
--form-spinner-bg-color	rgba(255, 255, 255, 0.8)
--form-spinner-display	flex
--form-spinner-filter	blur(4px)
--form-spinner-height	0
--form-spinner-justify-content	center
--form-spinner-left	0
--form-spinner-padding-bottom	0
--form-spinner-padding-left	0
--form-spinner-padding-right	0
--form-spinner-padding-top	0
--form-spinner-position	absolute
--form-spinner-top	0
--form-spinner-visible-height	100%
--form-spinner-visible-width	100%
--form-spinner-width	0
--form-spinner-z-index	10

---

Methods

The form element gives you a small set of methods you can call from your own JavaScript — from an Element Event → click in the builder, or any page/layout script. (Inline onclick="…" attributes are stripped by the site's content-security policy, so use one of those two instead.) Grab the element by its #id first, then call a method on it:

const form = document.getElementById('signup');   // your wd-form's #id

All four are async (they return a Promise).

submit() — submit the form

Re-checks the conditional rules, validates every field, then runs the form's configured submit action.

• Takes: nothing.
• If everything is valid → it does whatever the form is set to do in the Forms module: either redirects the browser to the destination page, or fires the formSubmitted event (carrying the values) for you to handle.
• If something is invalid → it marks the fields as touched (so their error messages show) and the Promise rejects with a helpful object you can inspect:

form.submit().catch(err => {
  // err.message  === "Form validation failed."
  // err.formFields === { email: { value: "", errors: ["Required"] }, ... }
});

• It does not show the spinner — that's toggleSpinner(), below.
• On a redirect form the Promise never settles: the browser navigates away as part of submitting, so don't put anything you depend on after await form.submit().

This is how your slotted submit button triggers the form — a bare type="submit" won't (see The submit button).

toggleSpinner(show) — show/hide the "submitting…" overlay

Handy when you handle the submission yourself (e.g. you listen for formSubmitted, do an async task, then finish) and want to show the busy state meanwhile.

• Takes: a boolean — true shows the spinner, false hides it.
• Returns: nothing.

form.toggleSpinner(true);    // busy…
await sendToMyApi();
form.toggleSpinner(false);   // done

setValue(fieldKey, value) — set a field's value

Sets a field programmatically, then re-validates that field and re-runs the conditional rules — exactly as if the visitor had typed it.

• Takes: the field's key (its key from the Forms module) and the value.
• Returns: nothing.

form.setValue('country', 'JO');

getFormValues() — read the current values

• Takes: nothing.
• Returns: a Promise that resolves to a plain object keyed by field key — e.g. { email: "a@b.com", country: "JO" } (section/heading fields are excluded).

const values = await form.getFormValues();

---

Notes

• This page is about the component (rendering & styling). To build the form itself — fields, validators, conditional rules, submit action/redirect — use the Forms module.
• The form also emits events for custom page scripts: formUpdated as values change, and (when it isn't redirecting) formSubmitted on a successful submit.