# @material/form-field

> Material Components for the web wrapper for laying out form fields and labels next to one another

Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @material/form-field
pnpm add @material/form-field
yarn add @material/form-field
bun add @material/form-field
```

## Health

**Score 28/100 (F)** — status: abandoned.

Positive: has types package; esm support; no vulnerabilities; popular repo.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 14.0.0 |
| Published | 2022-04-28 |
| First published | 2016-12-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/material__form-field) |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 182.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17051 |
| Maintainers | material-admin, yefim, abhiomkar, azakus, bicknellr, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv |
| Keywords | material components, material design, form |

## Links

- npm: https://www.npmjs.com/package/@material/form-field
- Repository: https://github.com/material-components/material-components-web
- Homepage: https://github.com/material-components/material-components-web#readme
- Issues: https://github.com/material-components/material-components-web/issues
- npm.io page: https://npm.io/package/@material/form-field

## Dependencies (7)

- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [@material/rtl](https://npm.io/package/@material/rtl.md) ^14.0.0
- [@material/base](https://npm.io/package/@material/base.md) ^14.0.0
- [@material/theme](https://npm.io/package/@material/theme.md) ^14.0.0
- [@material/ripple](https://npm.io/package/@material/ripple.md) ^14.0.0
- [@material/typography](https://npm.io/package/@material/typography.md) ^14.0.0
- [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 14.0.0 (latest) — 2022-04-28
- 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26
- 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20
- 4.0.0-alpha.0 (next) — 2019-08-07
- 15.0.0-canary.cfec83c74.0 — 2024-05-20
- 15.0.0-canary.2f5b899bc.0 — 2024-05-20
- 15.0.0-canary.f80ac92b0.0 — 2024-05-02
- 15.0.0-canary.4b35cb7d0.0 — 2024-05-02
- 15.0.0-canary.65c10a622.0 — 2024-04-25
- 15.0.0-canary.311f29a60.0 — 2024-04-23
- 15.0.0-canary.5bebc0064.0 — 2024-04-11
- 15.0.0-canary.68edc03c6.0 — 2024-04-08
- 15.0.0-canary.453a6248a.0 — 2024-03-25
- 15.0.0-canary.819498d8c.0 — 2024-03-15
- 15.0.0-canary.c43b3438b.0 — 2024-02-23
- … 1684 more at https://npm.io/package/@material/form-field/versions

## README

<!--docs:
title: "Form Fields"
layout: detail
section: components
path: /catalog/input-controls/form-fields/
-->

# Form Fields

MDC Form Field aligns an MDC Web form field (for example, a checkbox) with its label and makes it RTL-aware. It also activates a [ripple](../mdc-ripple) effect upon interacting with the label.

## Installation

```
npm install @material/form-field
```

## Demos

<ul class="icon-list">
  <li class="icon-list-item icon-list-item--link">
    <a href="https://material-components.github.io/material-components-web-catalog/#/component/radio">Demo with radio button</a>
  </li>
</ul>

## Basic Usage

### HTML Structure

Use the `mdc-form-field` element to wrap any combination of adjacent _input_ and _label_ elements of MDC Web form controls, such as [MDC Checkbox](../mdc-checkbox) or [MDC Radio](../mdc-radio). Here's an example with MDC Checkbox:

```html
<div class="mdc-form-field">
  <div class="mdc-checkbox">
    <input type="checkbox" id="my-checkbox" class="mdc-checkbox__native-control"/>
    <div class="mdc-checkbox__background">
      ...
    </div>
  </div>
  <label for="my-checkbox">This is my checkbox</label>
</div>
```

> _NOTE_: MDC Form Field is **not** intended for cases where a label and input are already handled together in a component's styles and logic. For example, [MDC Text Field](../mdc-textfield) already manages a label and input together under its own root element.

### JavaScript Instantiation

If you are using MDC Form Field with an MDC Web component that has a [ripple](../mdc-ripple) effect, you can instantiate `MDCFormField` and set its [`input` property](#mdcformfield-properties-and-methods) to activate the ripple effect upon interacting with the label. Here is an example with [MDC Checkbox](../mdc-checkbox):

```js
import {MDCFormField} from '@material/form-field';
import {MDCCheckbox} from '@material/checkbox';

const formField = new MDCFormField(document.querySelector('.mdc-form-field'));
const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
formField.input = checkbox;
```

> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.

## Variants

### Label position

By default, the input will be positioned before the label. You can position the input after the label by adding the `mdc-form-field--align-end` class:

```html
<div class="mdc-form-field mdc-form-field--align-end">
  <div class="mdc-checkbox">
    <input type="checkbox" id="my-checkbox" class="mdc-checkbox__native-control"/>
    <div class="mdc-checkbox__background">
      ...
    </div>
  </div>
  <label for="my-checkbox">This is my checkbox</label>
</div>
```

### Nowrap

If the label text is too long for a single line, it will wrap the text by default. You can force the text to stay on a single line and ellipse the overflow text by adding the `mdc-form-field--nowrap` class:

```html
<div class="mdc-form-field mdc-form-field--nowrap">
  <div class="mdc-checkbox">
    <input type="checkbox" id="my-checkbox" class="mdc-checkbox__native-control"/>
    <div class="mdc-checkbox__background">
      ...
    </div>
  </div>
  <label for="my-checkbox">This some really really really long text</label>
</div>
```

## `MDCFormField` Properties and Methods

Property | Value Type | Description
--- | --- | ---
`input` | String | Gets and sets the form field input. 

In order for the label ripple integration to work correctly, the `input` property needs to be set to a valid instance of an MDC Web input element which exposes a `ripple` getter. No action is taken if the `input` property is not set or the input instance doesn't expose a `ripple` getter.

## Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Form Field for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).

### `MDCFormFieldAdapter`

| Method Signature | Description |
| --- | --- |
| `registerInteractionHandler(type: string, handler: EventListener) => void` | Adds an event listener `handler` for event type `type` to the label. |
| `deregisterInteractionHandler(type: string, handler: EventListener) => void` | Removes an event listener `handler` for event type `type` to the label. |
| `activateInputRipple() => void` | Activates the ripple on the input element. Should call `activate` on the input element's `ripple` property. |
| `deactivateInputRipple() => void` | Deactivates the ripple on the input element. Should call `deactivate` on the input element's `ripple` property. |

---
_Source: https://npm.io/package/@material/form-field · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._