@material/form-field

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 effect upon interacting with the label.

Installation

npm install @material/form-field

Demos

• Demo with radio button

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 or MDC Radio. Here's an example with MDC Checkbox:

<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 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 effect, you can instantiate MDCFormField and set its input property to activate the ripple effect upon interacting with the label. Here is an example with MDC Checkbox:

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 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:

<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>

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.

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.

Changelog

6.0.0 (2020-04-22)

Bug Fixes

• auto-init: Fixed issue with multiple default exports (#5464) (8ddd5c6)
• button: Fix outline & ink color according to spec guidance (#5268) (ee1a68c)
• button: Fixed parameter default value in height mixin (#5244) (b0cecf1)
• checkbox: change checkbox event type from change to click and add some logic for IE browser (#5316) (2e491de), closes #4893
• checkbox: Disabled state colors in IE11 high contrast mode (#5263) (d6a1d4b)
• checkbox: Replace unique-id with custom color hash functio… (#5404) (7be9e4a)
• checkbox: update disabled color values (#5209) (821871e)
• checkbox: Use secondary and on-secondary as default colors (b95172e), closes #5730
• chips: .d.ts file generated with syntax error (d154836)
• chips: .d.ts file generated with syntax error (#5577) (98f7faa)
• chips: Do not throw error if chip set becomes empty (#5290) (f978109)
• chips: Fix browser back nav in FF when removing chip with… (#5537) (a1a0deb)
• chips: Handle IE/Edge specific key names in keyboard navigation logic (3657f88)
• chips: Move touch target inside primary action (ad3bbf7)
• circular-progress: Add .npmignore file to ignore typescript files when publishing (#5801) (f172b0f), closes #5800
• circular-progress: fix determinate transition typo & 4 color keyframes (a301636)
• circular-progress: Fix naming in package.json and add to jsBundleFactory (86f7cad)
• circular-progress: Force LTR layout (6a40ef2)
• circular-progress: Switch mixins import to [@use](https://github.com/use) (098ae32)
• core: Fix canary release by excluding test files from default tsconfig (#5317) (c916008)
• data-table: change svg attribute name viewbox to viewBox (#5483) (#5493) (f3adce8)
• data-table: Fix pagination box height (eb28b6e)
• data-table: Fixed default feature targeting query params of sort mixins (e33c49e)
• data-table: Hover styles for sortable header cell (d580805)
• data-table: Reverse the arrow direction icon for column sorting (a7c827f)
• data-table: unable to redefine colors in class-based themi… (#5751) (4d48051)
• data-table: unable to redefine colors in class-based theming (4b45b66)
• dialog: Move aria roles from dialog root to dialog surface… (#5239) (c704b71)
• elevation: Update overlay color mixin (#5331) (b723dfa)
• fab: Add missing dep to fab package.json. (#5236) (e0f6fd9)
• fab: Add overflow: visible to make touch target visible in… (#5241) (5850080)
• fab: Adjust fab line-height (#5254) (525989b)
• fab: Adjust fab line-height to center text (#5258) (591a6ad)
• floatinglabel: Estimate hidden scroll width (#5448) (981ec9b)
• linear-progress: Temporary rollback of #5656 while updating downstream dependencies (9cf5e98)
• linear-progress: support aria attributes (#5248) (7084b40), closes #5248
• list: Ensure disabled colors apply to primary and secondary text (#5322) (878a08b)
• list: No longer emits action event when disabled item selected (f352d03), closes #5571
• menu-surface: Use margin_to_edge as a viewport margin in calculations for autopositioning. (4b04cdb)
• menusurface: open and closed events not fired when already opened or closed (9cff431)
• menusurface: synchronous quick menu does not close on button click (45a6615)
• notched-outline: Restore component test (#5449) (4269133)
• radio: update disabled color values (#5210) (491fddc)
• select: Deduplicate change events (4ad1274), closes #5570
• select: Do not fire change event on programmatic change (#5255) (ec72968)
• select: Fix notch outline width when floating (#5319) (1c494e5)
• slider: slider track not visible (#5512) (f2426d2)
• slider: two change events fired on each up (d10412c)
• slider: use secondary custom property color for slider container (#5132) (aa8e43e)
• slider: Visual bug when slider value is displayed as "-0" (3fc3ab5)
• snackbar: add explicit width for label to wrap in ie11 (#5497) (cd49033)
• snackbar: adjust mixins to meet spec (#5477) (f16f15b)
• switch: add transform transition to switch control to avoid overflow-x issues (8c11ea2)
• switch: always set track to transparent border (9a169f4)
• switch: fix strict generic checks (7f5e0c2)
• switch: handle aria-checked correctly. (#5202) (#5357) (d245a1a)
• switch: set track border to be transparent (#5323) (397905b)
• switch: use CSS custom properties for theming (d6315ef)
• testing: Revert change from #5299. (#5324) (5fb62be)
• textfield: add placeholder mixins and fix disabled colors (#5360) (0a40ced)
• textfield: add separate classes for leading/trailing icons (#5367) (70c708d)
• textfield: change root element to <label> (#5439) (d8d9502)
• textfield: clean up input padding (8639c26)
• textfield: hide filled-variant floating label at <52px (#5553) (5ff3380)
• textfield: IE11 label overlapping placeholder (781434a)
• textfield: incorrect mixin forward path (#5554) (3e782d8)
• textfield: move ripple to separate element (c541ebe)
• textfield: outlined trailing icon's position (#5496) (93e2288)
• textfield: prevent placeholder styles from collapsing with minifiers (d07c78d)
• add missing SASS dependencies (#5337) (d2ae6e1)
• textfield: remove absolute positioning from icons (1e13d1d)
• textfield: remove deprecated dense variant in favor of density (776291e), closes #4142
• textfield: use correct disabled colors for IE11 high contrast (5353985)
• Remove edge detection for CSS custom properties (#5264) (fe444ac)
• server-side rendering errors in linear progress and slider (7d0b983)

Code Refactoring

• migrate to the Sass module system (#5453) (faa9af3)
• grid-list: Deprecate component (#5499) (cf33f11)
• linear-progress: Restructure buffer DOM to allow translucent buffer (98b8434)
• linear-progress: Restructure buffer DOM to allow translucent buffer (9372e49)
• select: Fix alignment issues, upgrade anchor to interactive element (28d10a9), closes #5428
• touchtarget: Rename mdc-touch-target-component => mdc… (#5245) (afe0dd1)

Features

• button: Add disabled state color mixins (#5232) (b5eb51e)
• button: Add overflow ellipsis mixin (#5352) (47949b0)
• button: Expand outlined touch target to include side borders (ce6cb70)
• button: Setup elevation overlay (#5256) (3cbee6d)
• card: Add elevation overlay structure (#5282) (aa0eba4)
• checkbox: Add support for checkbox CSS-only indeterminate checkbox (b273afa)
• chips: Add chips styling (1db5c9f)
• chips: Add elevation overlay structure (#5279) (3e560b3)
• chips: Add focus{in|out} handlers (10af6cf)
• chips: Add keyCode support (82fa986)
• chips: Add trailing action feature targeting test (bec0659)
• chips: Announce when chips are removed (b3f70eb)
• chips: Consolidate interaction event handlers (#5251) (5729943)
• chips: Create trailing action business logic (9ebee4c)
• chips: Expose trailing action chip files (6b48781)
• chips: Restructure trailing action mixins (05f5e15)
• circular-progress: Add foundation methods to get isDeterminate and progress value (7d8f9c8)
• circular-progress: Add Sass styles and tests (bd33cb5)
• circular-progress: Add TS for foundation, adapter, component with tests (548b1d4)
• data-table: Add base styles to support pagination. (927fa90)
• data-table: Add foundation methods to support loading state. (e75deb8)
• data-table: Added styles for table in loading state (35a32aa)
• data-table: Added styles to support column sorting. (17b9699)
• data-table: Foundation changes to support column sorting (6ee0355)
• data-table: Set progress indicator styles based on table body height (c026422)
• dialog: Add elevation overlay structure (#5283) (b8bc4a2)
• dom: Add focus trap utility. (#5505) (63f357d)
• dom: Add keyboard support (5f24faa)
• dom: Create announcer utility (32c1df1)
• elevation: Add elevation overlay mixins (#5249) (b4cfdc4)
• elevation: Update elevation mixins (#5304) (ba879b6)
• fab: Add elevation overlay structure (#5278) (e89750d)
• fab: Add outline in high-contrast mode (deda86d)
• fab: Add support for increased touch target to mini FAB. (#5231) (0c4d8f3)
• floating-label: add feature targeting for styles (#5287) (b240bcc)
• form-field: Add support for space-between (e84b9c8), closes #5747
• formfield: add nowrap class/prop to MDC/MWC (c4b4bba)
• icon-button: Add disabled state color mixins (#5246) (7161170)
• iconbutton: Add icon button variant which supports toggling aria label. (f838c6e)
• line-ripple: add active/inactive states to line-ripple (b6c7f62)
• line-ripple: add feature targeting for styles (#5292) (391674a)
• linear-progress: Add foundation methods to fetch progress and determinate state. (4dc45af)
• menu: Add elevation overlay structure (#5280) (7fd17ce)
• menu: Add mixin to flatten menu top when opened-below anchor (1e17c49)
• menu-surface: Add support for flipping menu corner horizontally. (7b44824)
• notched-outline: add feature targeting for styles (#5289) (c483774)
• progress-indicator: Add common interface for progress indicators (#5564) (ea863cb)
• ripple: Reorganize ripple opacities (008c4d3)
• switch: Add elevation overlay structure (#5281) (50f110a)
• switch: Restructure DOM (#5312) (0ec1fab)
• text-field: Add disabled state color mixins (#5208) (66299b6)
• text-field: add feature targeting for styles (#5378) (e8a9936)
• text-field: Truncate floating label width w/ icons (c141801)
• textfield: add end-alignment (#5356) (847dd1a)
• textfield: add filled class variant (b70bc60)
• textfield: add forced LTR input (490fbdc)
• textfield: add prefix and suffix (6601d24), closes #1892
• Add index stylesheets to each MDC Web package (#5539) (1814866)
• Add index stylesheets to mdc-image-list and mdc-layout-gr… (#5546) (3a85313)
• Use @use syntax in material-components-web Sass file and… (#5573) (b4727e4)
• textfield: add specific label-floating class (a88c8e4)
• textfield: allow character counter to be moved outside of the textarea. (84e7ed5)
• textfield: Create float transition mixin (ca61b65)
• textfield: Limit notched outline max-width (0ab62a6)
• typography: add container baseline mixins for flexbox (69edc6e)

Reverts

• Revert "feat(switch): Add elevation overlay structure (#5281)" (#5329) (1fbf5bd), closes #5281 #5329
• "fix(checkbox): change checkbox event type from change to click and add some logic for IE browser" (ba30399)
• feat(chips): Consolidate interaction event handlers (#5251) (#5301) (5e45d77)
• fix(chips): Do not throw error if chip set becomes empty (#5300) (d10e8cd)
• fix(select): Do not fire change event on programmatic change (#5255) (#5302) (ad9dfe7)

BREAKING CHANGES

• select: HTML Markup significantly changed, see README; REMOVED adapter methods isSelectedTextFocused, getSelectedTextAttr, setSelectedTextAttr; ADDED adapter methods isSelectAnchorFocused, getSelectAnchorAttr, setSelectAnchorAttr; removed variables outlined-dense-label-position-y, icon-padding; added variables minimum-height-for-filled-label, filled-baseline-top, selected-text-height, anchor-padding-left, anchor-padding-left-with-leading-icon, anchor-padding-right.

• text-field: Redundant mixins mdc-text-field-textarea-fill-color, mdc-text-field-textarea-stroke-color, mdc-text-field-fullwidth-bottom-line-color removed. Instead, use mdc-text-field-fill-color, mdc-text-field-outline-color, and mdc-text-field-bottom-line-color respectively to achieve the same effect.

• textfield: mdc-text-field--dense and associated mixins/variables have been removed. Use the density() mixin instead.

• textfield: removed the following variables: $input-padding, $input-padding-top, $input-padding-bottom, $outlined-input-padding-top, $outlined-input-padding-bottom, $input-border-bottom

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• typography: typography.baseline-top() and typography.baseline-bottom() are now private. Use typography.baseline() for containers and typography.text-baseline() for text with $top and $bottom params.

• chips: The touch target and text now appear inside the primary action element. Please see the readme for markup changes.

• textfield: filled text fields must include a <div class="mdc-text-field__ripple"></div>

• textfield: Filled textfields will no longer show a floating label at certain densities. This can be overridden by setting $mdc-text-field-minimum-height-for-filled-label: 40px

• chips: Both MDCChipAdapter and MDCChipSetAdapter have new methods. MDCChipSetFoundation event handlers now accept the corresponding chip event detail interface as the sole argument. The root property has been removed from the MDCChipRemovalEventDetail interface.

• line-ripple: mdc-line-ripple-color() mixin has been renamed to mdc-line-ripple-active-color()

• textfield: Default textfields must now specify mdc-text-field--filled. Disabled outlined textfields no longer have a shaded background. Height mixin no longer specifies a baseline override, use typography's baseline-top mixin.

• Four variables and a mixin in mdc-textfield were renamed to use a mdc-text-field- prefix when depended on via @import (formerly mdc-required-text-field-label-asterisk_, now required-label-asterisk_).

• textfield: icons must use .mdc-text-field__icon--leading or .mdc-text-field__icon--trailing classes. mdc-text-field-icon-color() mixin has been split into mdc-text-field-leading-icon-color() and mdc-text-field-trailing-icon-color().

• switch: Added setNativeControlAttr method in mdc-switch adapter.

• checkbox: remove event listener for 'change' and add event listener for 'click'.

• Add handleClick() method in foundation to handle click event.
• Add setCheck() method into component to change check status.

• switch: Switch DOM structure has changed. See switch README for details
• button: Variable $mdc-button-disabled-container-fill-color renamed to $mdc-button-disabled-container-color.
• Removed $edgeOptOut option from mdc-theme-prop() Sass mixin.
• chips: the handleInteraction and handleTrailingIconInteraction handlers have been removed from the MDCChipFoundation. The handleClick handler has been added to the MDCChipFoundation
• Adds new adapter methods to MDCLinearProgressAdapter.
• elevation: Functions moved into the _functions.scss file
• touchtarget: Renames mixin from mdc-touch-target-component => mdc-touch-target-margin
• grid-list: Per the deprecation notice for grid-list, this component has been removed from MDC-Web. Some of its functionalities are available in the MDC Image List package instead. It is recommended that you migrate to the mdc-image-list package to continue to receive new features and updates.