Form

Collect fields, validate them, and emit a submission event. ds-form stands what it holds in a column, checks it when submitted and reports the values. The page decides what happens to them: with no action, nothing leaves the browser.

Reserve a workshop place

Labels, fields and actions form a small vertical rhythm. Submitting stays inside this preview.

Search the archive

A compact single-purpose form with a query and one action.

A local form

Type a name and submit. The result stays in this preview.

The example has no action endpoint. Submit an empty field to see validation, then enter a name to see the form data. It sends no server request.

A submit or reset button works as it does in a native <form>: a <button type="submit"> or <button type="reset">, the same inside <ds-button control="slotted">, or <ds-button type="submit">. A <button> without a type submits, as in HTML, so give every other button type="button". Enter submits from a one-line field. On a button it presses that button, and in a multiline field it starts a new line.

Each child takes the form’s width, half a square from the next. The form reads every element with a name among its children and inside their shadow roots. A checkbox gives true or false, a radio group the value of its checked radio, and anything else its value.

Submitting validates first. A ds-input with required and no value fails, and so does a native input, textarea or select that fails its own check. A failure sends form-invalid with a message for each field’s name, and nothing is submitted. A valid form sends form-submit. A second submit while one is running is ignored.

With an action, the form then sends the values with fetch as JSON, using method, and reports the answer in form-response or a failed request in form-error.

Reset puts every field back to what it started with, as a native form does: the value it was written with, or empty if it had none, and each checkbox and radio as it first stood.

The controls stay native, so their labels, required state and keyboard work as usual: name every field, with label on a ds-input or a native label. The form draws no error message of its own. Show what form-invalid reports beside its field, in words.

AttributeTypeDefaultWhat it does
actionstringEmptyOptional server endpoint.
methodstringpostHTTP method for a server submission.
namestringEmptyForm name.
novalidatebooleanfalseSkips validation.
autocompletestringonAutocomplete preference.
disabledbooleanfalseDims the form and stops the pointer. It is a look only: keys still work, so disable the controls too.
SlotWhat it holds
DefaultThe fields and buttons.
const form = document.querySelector('ds-form');form.addEventListener('form-submit', (event) => {  console.log(event.detail.data);});

form-invalid reports validation errors. form-reset, form-response and form-error report reset and server outcomes. Methods are getFormData(), validate(), reset() and submit().

EventDetailWhat it means
form-submitdataThe form is valid; these are its values.
form-invalidAn error message for each field’s nameValidation failed.
form-resetNoneThe fields went back to what they started with.
form-responseresponse, dataThe action answered.
form-errorerror, dataThe request to action failed.

All five bubble.

MethodWhat it does
getFormData()Returns the values, by name.
validate()Returns valid and errors without submitting.
reset()Puts the fields back to what they started with and sends form-reset.
submit()Validates, then submits.

It has no tokens of its own. Copy form through Sync 1. Native platforms use their own forms.

Input · Button