The m3e-form-field is a container for form controls that applies Material Design styling and behavior. Supported controls include: input, select, textarea, and m3e-input-chip-set.

npm i @m3e/form-field

This section outlines usage examples and configuration guidance for the components in this package.

There are two form field appearance variants: outlined (default) and filled. Use the variant attribute to change the appearance.

<m3e-form-field variant="outlined">
  <label slot="label" for="fld">Outlined</label>
  <input id="fld" />
</m3e-form-field>
<!-- Additional variants omitted for brevity -->

When a form field's control is empty, the label is presented over the control instead of above. You can change this behavior using the float-label attribute. Supported values include always and auto (default).

<m3e-form-field float-label="always">
  <label slot="label" for="fld">Always float label</label>
  <input id="fld" />
</m3e-form-field>

Hint labels are additional descriptive text that appear in a field's subscript. Use the hint slot to specify a hint. By default, a field's subscript is hidden until focused or when a field is invalid. Use the hide-subscript attribute to control this behavior. Supported values include: always, auto (default), and never. Using always will remove the space reserved for a field's subscript.

The following example illustrates use of the hint slot with hide-subscript set to never.

<m3e-form-field hide-subscript="never">
  <label slot="label" for="fld">Field w/ hint</label>
  <input id="fld" />
  <span slot="hint">Hint text</span>
</m3e-form-field>

Errors are hidden by default and only become visible after the user has interacted with the field—such as focusing and then blurring—or after the parent form has been submitted. This behavior ensures that validation feedback is contextually relevant and non-intrusive, appearing only when the user is likely to expect it.

When an error message is shown, it occupies the same subscript region beneath the field that is normally used for the hint label. To prevent visual overlap and maintain clarity, the hint is automatically hidden whenever an error is displayed.

<m3e-form-field>
  <label slot="label" for="fld5">Required field</label>
  <input id="fld5" required />
  <span slot="hint">Hint text</span>
</m3e-form-field>

By default, the validation message of a field's control is presented in a field's subscript. You can specify custom error messages using the error slot.

<m3e-form-field>
  <label slot="label" for="fld">Required field</label>
  <input id="fld" required />
  <span slot="hint">Hint text</span>
  <span slot="error">Custom error message</span>
</m3e-form-field>

By default, required fields will present a marker next to the field's label. Use the hide-required-marker attribute to remove it.

<m3e-form-field hide-required-marker>
  <label slot="label" for="fld">Required field</label>
  <input id="fld" required />
</m3e-form-field>

Content can be included before or after the field's control to serve as a prefix or suffix. This content is rendered inside the same visual container that wraps the form control, ensuring consistent alignment, spacing, and styling.

Use the prefix and suffix slots for icons and buttons. For textual content, use the prefix-text and suffix-text slots.

<m3e-form-field>
  <label slot="label" for="fld">Amount</label>
  <span slot="prefix-text">$</span>
  <input id="fld" type="number" placeholder="0" />
  <span slot="suffix-text">.00</span>
  <m3e-icon-button slot="suffix">
    <m3e-icon name="clear"></m3e-icon>
  </m3e-icon-button>
</m3e-form-field>

The m3e-form-field will hide hint labels and error messages from the accessibility tree and use a visually hidden element to present them to assistive technologies. Their IDs are added to the aria-describedby attribute of the field's control.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/form-field/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.