Form

A form builds a set of fields from a layout, and keeps their data: it reads and sets it, knows when it has changed, validates it and submits it. M3 has no form component; its fields are mtrl's, such as text fields, and M3's guidance for them applies.

From mtrl-addons, checked against 0.9.0-next.1. mtrl-addons has no web components, and a form's layout names mtrl's factories, which the neutral examples cannot, so these examples are plain JavaScript: the vanilla factory, which works in any framework.

Usage

The layout is an array of [factory, name, options]. A field named info.<key> (or data.<key>) is the data's <key>; buttons named submit and cancel submit and reset the form, and are enabled while its data differs from what it started with.

import { createForm } from 'mtrl-addons';
import { createTextfield, createSwitch, createButton } from 'mtrl';

const form = createForm({
  layout: [
    [createTextfield, 'info.name', { label: 'Name' }],
    [createTextfield, 'info.email', { label: 'Email', type: 'email' }],
    [createSwitch, 'info.newsletter', { label: 'Newsletter' }],
    [createButton, 'cancel', { text: 'Cancel', variant: 'text' }],
    [createButton, 'submit', { text: 'Save', variant: 'filled' }],
  ],
  data: { name: 'Ada', email: '[email protected]', newsletter: true },
  onSubmit: (data) => myApi.saveUser(data),
  container: document.body,
});

A layout item can also be an element, ['section', { class: 'details' }, ...children], to group the fields.

Examples

Validation

Each rule validates one field's value, with all the data at hand: it returns true, or a message. validate() shows the messages on the fields, and submit() validates first.

import { createForm } from 'mtrl-addons';
import { createTextfield } from 'mtrl';

const form = createForm({
  layout: [
    [createTextfield, 'info.password', { label: 'Password', type: 'password' }],
    [createTextfield, 'info.confirm', { label: 'Confirm password', type: 'password' }],
  ],
  validation: [
    { field: 'password', validate: (value) => String(value ?? '').length >= 8 || 'At least 8 characters' },
    { field: 'confirm', validate: (value, data) => value === data.password || 'The passwords differ' },
  ],
  container: document.body,
});

const { valid, errors } = form.validate();

Submitting

With action, submit() sends the data as JSON with fetch, by method (POST by default); onSubmit replaces the request. While it submits, the controls are disabled.

import { createForm } from 'mtrl-addons';
import { createTextfield, createButton } from 'mtrl';

const form = createForm({
  action: '/api/profile',
  method: 'PUT',
  layout: [
    [createTextfield, 'info.city', { label: 'City' }],
    [createButton, 'submit', { text: 'Save', variant: 'filled' }],
  ],
  container: document.body,
});

form.on('submit:success', () => router.go('/profile'));

Loading data

setData(data, true) sets the data as the new starting point, so the form is not modified. setData(data) changes it as an edit would.

import { createForm } from 'mtrl-addons';
import { createTextfield } from 'mtrl';

const form = createForm({
  layout: [[createTextfield, 'info.name', { label: 'Name' }]],
  container: document.body,
});

form.setData({ name: 'Grace' }, true);

protectChanges guards unsaved changes: beforeUnload asks before the page is left, and onDataOverwrite blocks clicks outside the form and emits data:conflict, whose cancel() keeps the changes and proceed() discards them. Recipes such as an account form or a sign-in form are planned for Examples.

API

Options

Methods

DATA_STATE and FORM_EVENTS are in mtrl-addons/components/form/constants.

Events

Accessibility

• A native <form>; each field keeps its own semantics, label and keyboard.
• A validation message is the field's supporting text, and its error state its aria-invalid.
• Enter in a field does not submit the form: submitting is the submit button's, or submit().

Styling

.mtrl-form { }
.mtrl-form--modified, .mtrl-form--submitting { }