@material/form-field
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/material__form-field package

    13.0.0 • Public • Published

    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

    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>

    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:

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

    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.

    Install

    npm i @material/form-field

    DownloadsWeekly Downloads

    52,827

    Version

    13.0.0

    License

    MIT

    Unpacked Size

    188 kB

    Total Files

    32

    Last publish

    Collaborators

    • material-admin
    • yefim
    • abhiomkar
    • azakus
    • bicknellr
    • aprigogin
    • patrickrodee
    • aomarks
    • emarquez
    • allanchen
    • esgonzalez
    • asyncliz
    • candysonya
    • ssuarez
    • taylorv