Forms

GitHub Source Link @nycopportunity/pattern-elements/src/elements/forms

Demonstration
Please select one of these options
Please check as many options that apply
Code

Forms in the Opportunity Standard follow the usage guidelines of the U.S. Web Design System (USWDS) Form Component. Forms use different Question Patterns to gather specific pieces of information. More information about these patterns can be found on the Question page.

Validation and Accessibility

Proper markup and aria labeling are required for each Question. They appear similar stylistically but there is a difference in the markup between questions with one or multiple inputs. Proper id, name, and aria attributes are also required for labels, option inputs, SVG icons, and validation messages.

Questions use validation from the Patterns Scripts utility library. This script will display visual feedback regarding missing or invalid answers and toggle appropriate aria attributes to announce feedback to screen readers. The aria-live="polite" attribute on the message declares error messages that are not visible in the default state.

The aria-invalid="true" attribute illustrates to screen readers that the input is not valid, and the aria-describedby attribute indicates the input’s error description.

Validity is assessed using the Constraint Validation API based on values of the type, required, and pattern attributes. If any validity constraints are not met, then the localized validationMessage is displayed. Examples include “This field is required” or “Please provide a valid …”

Validation occurs on the blur event or when the user shifts focus away from the input.

Validation Anchor Link Validation

Global Script

Forms require JavaScript for validation and accessibility. To use validation through the global script use the following code. An optional selector targeting the form may be supplied as the first argument to the .validate() method. The second optional argument is a function that handles the form data after it passes validation.

<form data-js="validate" action="/my/action/" method="post">
  <!-- Form questions here -->
</form>

<script src="@nycopportunity/standard/dist/js/default.js"></script>

<script>
  var Standard = new Default();

  Standard.validate();

  // or

  // Accepts a selector string (argument one) and function (argument two) for submission handling
  Standard.validate('[data-js="validate"]', function(event) {
    event.preventDefault();

    // Add your own custom submission handler here
  });
</script>

Validation messages will appear when the user…

  • leaves a required question blank,

  • enters an answer doesn’t match the specified input type,

  • enters an answer that does not match a specified pattern,

  • or tries to submit the form without filling out any required fields.

For any of these conditions to be met…

Module Import

The form validation source exists in the Patterns Scripts utility library. Install the @nycopportunity/pttrn-scripts module to import the module. This method allows the specification of watching for input errors on blur, setting the error container’s selector, and other customizations. Refer to the source for details.

import Forms from '@nycopportunity/patterns-scripts/src/forms/forms';

this.form = new Forms(document.querySelector('[data-js="validate"]'));

this.form.submit = (event) => {
  event.preventDefault();
  // Submission handler
};

this.form.selectors.ERROR_MESSAGE_PARENT = '.c-question__container';

this.form.watch();