Form

Material Design 3 form wrapper for collecting values, validating fields, and coordinating submission across multiple inputs. Not intended to replace field-level semantics; labels and constraints must still be defined on individual controls.

Basic Usage

A minimal form with required fields and submit handling. The form wrapper centralizes state, validation, and event flow across child controls.

Sign In Clear
Output: Submit the form to see collected data. 
<ds-form name="basic">
  <ds-text-field name="email" type="email" required></ds-text-field>
  <ds-text-field name="password" type="password" required minlength="8"></ds-text-field>
  <ds-button type="submit">Sign In</ds-button>
</ds-form>

Initial Value

Use value and checked attributes to prefill fields.

<ds-form name="prefilled">
  <ds-text-field name="firstName" value="Jamie"></ds-text-field>
  <ds-text-field name="lastName" value="Rios"></ds-text-field>
  <ds-checkbox name="newsletter" checked>Subscribe</ds-checkbox>
</ds-form>

Variants and Formats

Use layout wrappers to adapt form presentation.

Stacked Layout

<ds-form name="stacked">
  <ds-text-field name="city"></ds-text-field>
  <ds-text-field name="state"></ds-text-field>
</ds-form>

Split Layout

 
<ds-form name="split">
  <div class="grid">
    <ds-text-field name="city"></ds-text-field>
    <ds-text-field name="state"></ds-text-field>
    <ds-text-field name="zip"></ds-text-field>
  </div>
</ds-form>

States

Validation feedback and optional validation control.

Validation Errors

Validate
Output: Interact with fields to see validation.

Validation Disabled

Submit
Output: Validation is bypassed when novalidate is set.

Interactive Example

Log events as users interact with the form.

Send Clear Log
Event Log 
    form.addEventListener("ds-form:change", (event) => {
  console.log(event.detail.name, event.detail.value);
});

form.addEventListener("ds-form:submit", (event) => {
  console.log(event.detail.values);
});

    API

    Attributes

    Attribute Type Default Description
    name string - Form name identifier.
    novalidate boolean false Bypass built-in validation.

    Events

    Event Detail Description
    ds-form:submit { values: Object, isValid: boolean } Fired on form submission with valid data.
    ds-form:change { name: string, value: any, values: Object } Fired when any field value changes.
    ds-form:reset - Fired when form is reset.
    ds-form:validity-change { isValid: boolean } Fired when overall form validity changes.

    Methods

    Method Returns Description
    getValues() Object Get all field values.
    getValue(name) any Get a specific field value.
    setValue(name, value) void Set a field value programmatically.
    validate() boolean Validate all fields.
    isValid() boolean Return current validity state.
    getErrors() Object Get current validation errors.
    getTouched() Set Get touched fields.
    getDirty() Set Get dirty fields.
    markTouched(name) void Mark a field as touched.
    markAllTouched() void Mark all fields as touched.
    submit() boolean Alias for validate().
    reset() void Reset field values and internal state.

    CSS Parts

    Part Description
    container Main form container element.
    error-summary Error summary and list container.

    CSS Custom Properties

    Property Description
    --ds-space-4 Controls vertical spacing between fields.
    --ds-space-2 Controls error list spacing.
    --ds-radius-sm Controls error summary corner radius.
    --md-sys-color-error-container Error summary background color.
    --md-sys-color-on-error-container Error summary text color.
    --md-sys-typescale-body-medium-size Error summary text size.

    Accessibility

    Keyboard Interaction

    Key Context Expected Result
    Tab / Shift+Tab Form controls Moves focus through fields and actions in order
    Enter Form submit context Submits the form through configured validation flow

    Semantics

    • Child controls expose ARIA state and validation semantics.
    • Visible focus indicators are inherited from child components.
    • Validation messaging should remain programmatically associated to fields.

    Usage Guidelines

    • When to use: Use for multi-field submission flows that require coordinated validation and value collection.
    • When not to use: Avoid wrapping isolated single-field interactions that can submit independently.
    • Composition: Pair each field with labels/helper text and use novalidate only for custom validation pipelines.
    • Common mistakes: Omitting required field semantics in children causes inconsistent error handling and accessibility output.