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.
Design examples
Section titled “Design examples”Labels, fields and actions form a small vertical rhythm. Submitting stays inside this preview.
<section class="specimen">
<ds-form><ds-input label="Name" name="name" value="Nia Vale" required></ds-input><ds-input label="Email" name="email" type="email" placeholder="you@example.com" required></ds-input><ds-gap></ds-gap><ds-button primary type="submit">Reserve a place</ds-button></ds-form>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> A compact single-purpose form with a query and one action.
<section class="specimen">
<ds-form><ds-input label="Search recordings" name="query" value="rain"></ds-input><ds-gap size="05"></ds-gap><ds-button primary type="submit"><span class="mark"><ds-icon type="search" size="large" aria-hidden="true"></ds-icon></span>Search</ds-button></ds-form>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> Try it
Section titled “Try it”Type a name and submit. The result stays in this preview.
<ds-form>
<ds-input label="Your name" name="name" required></ds-input>
<button type="submit">Try submission</button>
</ds-form> Try it locally
Section titled “Try it locally”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.
Behaviour
Section titled “Behaviour”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.
Accessibility
Section titled “Accessibility”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.
Attributes
Section titled “Attributes”| Attribute | Type | Default | What it does |
|---|---|---|---|
action | string | Empty | Optional server endpoint. |
method | string | post | HTTP method for a server submission. |
name | string | Empty | Form name. |
novalidate | boolean | false | Skips validation. |
autocomplete | string | on | Autocomplete preference. |
disabled | boolean | false | Dims the form and stops the pointer. It is a look only: keys still work, so disable the controls too. |
| Slot | What it holds |
|---|---|
| Default | The fields and buttons. |
Events and methods
Section titled “Events and methods”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().
| Event | Detail | What it means |
|---|---|---|
form-submit | data | The form is valid; these are its values. |
form-invalid | An error message for each field’s name | Validation failed. |
form-reset | None | The fields went back to what they started with. |
form-response | response, data | The action answered. |
form-error | error, data | The request to action failed. |
All five bubble.
| Method | What 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.