Large Forms - Accordion

Overview

A form is a collection of labeled inputs that allows the user to input or update a set of data.

Forms typically include the following elements:

• A set of one or more fields. Each field includes:
  • A text label to identify the field
  • An input element that allows the user to enter/update data for the field
• Buttons for controlling the form. We display these buttons at the top of the form. These buttons include:
  • Save: Validates the form data and posts the form if no validation errors are found.
  • Cancel: Abandons the form data and returns the user to the previous location in the application.
  • Next: Move to the next screen of fields in a wizard-based form.
  • Back: Move to the previous screen of fields in a wizard-based form.
• Validation errors identify invalid data in the form.
  • Field-level validation errors are associated with fields in the form. We display each of these directly below the field so the user can see both the data and the validation error together, making it easier for them to understand and correct the error.
  • Form-level validation errors are for the entire form and are not associated with an individual field in the form. We display these above the fields.

In smaller forms that don’t require scrolling, it’s simple for the user to see all of these elements at the same time.

But larger forms — where the user has to scroll the page in order to see all the fields — can present some unique challenges:

• How can we keep all of these types of form elements easily accessible as the user scrolls down the page?
• How can we break a large form into smaller pieces to help the user progress through the form?
• How can we make a large form usable even at mobile size?

This pattern discusses how we can address the challenges presented by larger forms. (Note that forms can also be used for gathering search query inputs, but that specific use case is outside the scope of this pattern.)

Keeping the primary form elements easily accessible

Earlier we mentioned that the three primary elements of forms include fields, validation errors, and buttons. These naturally break down into two categories:

• Data elements: The fields and field-level validation errors
• Control elements: The control buttons: Save, Cancel, Next and Back

We display the control elements (buttons) at the top of the form, typically in the display block toolbar.

We display the data elements (fields and any field-level validation errors) below the control elements.

Because the number of data elements can vary a great deal from form to form – anywhere from one field to hundreds of fields – we use vertical scrolling to manage any overflow. I.e. the user scrolls down to access any form fields that are out of view.

As the user scrolls down, the control buttons will scroll out of view. Since these buttons should remain accessible for usability, we use two techniques to keep the control buttons easily accessible:

• Floating toolbar: The floating toolbar appears at the top of the view after the user scrolls a little down the page and hides again if the user scrolls back up to the top of the view. If we display the control elements (e.g. Save/Cancel buttons) in both the display block toolbar (which can scroll out of view) and in the floating toolbar, then the user will always have easy access to these buttons.
• Fixed layout: By default, the entire view will scroll vertically when there are more elements than can be seen in the viewport at once. With fixed layout however, we fix 1 or more display blocks in a layout that does not scroll, instead using vertical scrollbars within each display block as needed. This approach keeps the display block toolbar always visible, including the control buttons.

Both of those techniques work well at larger screen sizes, but at mobile size, fixed layout drops into a vertically scrolling layout which allows the control buttons to scroll out of view. So we display the control buttons in both the display block toolbar and in the floating toolbar, even if fixed layout is used. A fixed-layout view can and should include a floating toolbar; this displays at mobile size when the user scrolls down the page.

Navigating through field-level validation errors

Another challenge with large forms is making it easy for the user to find and fix validation errors in the form inputs.

This is less of a problem with small forms, since the fields and any validation errors are mostly visible at a glance. But if the form contains a large number of fields, the user sees less fields at a time, which can make it difficult for the user to know where the field-level validation errors are.

And that’s if the user even knows that there are validation errors in the first place. If all fields with validation errors are currently scrolled out of view, the only clue that the user has that validation errors exist is the fact that the Save button is disabled.

The validation error navigator helps solve these problems.

• Add the validation error navigator to the display block toolbar and the floating toolbar. It’s visible whenever the form contains any field-level validation errors and hides when there are no validation errors in the form.
• The validation error navigator specifies the number of validation errors present in the form. Its very presence is a reliable indicator to the user that the form contains validation errors.
• The validation error navigator includes arrow buttons for navigating between validation errors. Pressing the “next” button scrolls to and sets focus to the next validation error in the form. The “back” button does the same for the previous validation error in the form.

The validation error navigator must appear to the right of all other buttons in the toolbar. The typical order (left to right) will be Save button, Cancel button, then the validation error navigator.

The validation error navigator does not reproduce the list of validation errors, it simply alerts the user to the fact that the form contains validation errors and helps the user navigate to and fix each validation error.

Breaking form fields into smaller chunks

We can help make large forms more manageable by breaking them into smaller sections.

This can be helpful at any screen size but is especially helpful on smaller screen sizes like mobile, where the user can see far fewer fields on the screen at a time.

The fields in each section of the form should be related, as part of a cohesive sub-group.

For example, you might break a purchase form down into one section with fields for the mailing address, another section with fields for the billing address, another with fields for the payment options, and so forth. It’s important to keep each section large enough to remain cohesive but also small enough to benefit from breaking the form into chunks (and to work well on smaller devices like mobile).

We support two techniques for breaking forms into smaller sections that work well across all screen widths: accordion group boxes and wizards. The accordion group boxes approach is described below. See Large Forms - Wizard for details on using a wizard for large forms.

Using accordion group boxes for large forms

Accordion group boxes are a collection of expandable group boxes where only one group box is expanded at a time. Expanding one group box automatically collapses all other group boxes in the form. The vertical nature of the stacked group boxes works well with the page’s vertical scrolling.

The accordion group boxes are stacked vertically, one on top of the next. Each group box title displays the name for its section of the form.

Your application should display error styling for each accordion group box that contains a field with a validation error.

The validation error navigator allows the user to navigate to each field that has a validation error and fix it. As the user navigates to each validation error, your application must first expand the accordion group box that contains the validation error, scroll the field into view, then set focus to it.

Combining grouping techniques

While we don’t recommend this for most forms, it is possible to combine these two grouping techniques in the same form.

To do this, first start by breaking the form down into a set of high-level sections, then display them as separate steps in a wizard. Then, as needed, break down the fields within each step of the wizard using accordion group boxes within that wizard step.

Ensuring that forms work well at mobile size

The techniques in this pattern work well at all screen sizes, including mobile.

• The floating toolbar keeps the form’s control buttons always accessible, regardless of how far the user has scrolled down in the form.
• The validation error navigator helps the user (a) see that the form contains validation errors and (b) navigate between validation errors, without consuming any new space in the view.
• Breaking the form into sections helps reduce the number of fields the user has to scroll through at a time, which is even more important in the limited viewport that mobile devices offer.
  • Of the two grouping techniques, the wizard approach is a little more mobile-friendly because the user only sees fields for the current step. This limits the user’s navigation to one step at a time using the Back/Next buttons, but this is appropriate behavior for a smaller device.
  • The accordion group box approach also works well on mobile, although the user has to visually skip over any collapsed group boxes in the view.

Development

Web component development

Elements of a Large Form that uses Accordion Group Boxes

• Save/Cancel buttons in the display block toolbar
• A validation error navigator in the display block toolbar, for quickly identifying validation errors in the form and navigating between them
• A set of accordion group boxes, each of which contains one section of the form
  • Stack the accordion group boxes vertically, one on top of the next.
  • Display the form section name as the group box title.
  • The vertical nature of the stacked group boxes fits well with the vertical scrolling for the page.

You must also include a floating toolbar for the view that duplicates the Save/Cancel buttons and the validation error navigator. This ensures that the user always has access to these important navigation buttons and will always be able to tell if the form contains a validation error.

In order to navigate programmatically to the correct input, you’ll need to add an id attribute to the outer div for each form field based on its formControlName attribute. Add a ‘field-’ prefix to the formControlName value to calculate the field’s id value.

Example: Let’s say you have a “Home Phone” field in your form and its formControlName is “HomePhone”. Add an id to the outer div for this field with the value “field-HomePhone”.

<input id="field-name" formControlName="name" type="text" class="rui-form-control" />

Using accordion group boxes means that only one group box is visible at a time. This is typically desirable since it can help cut down on scrolling. If you find a case where the user needs to see fields from multiple group boxes at the same time, you should first see if it makes sense to combine those fields into the same group box without making that section too large. If that approach doesn’t work for your use case, it is technically possible to use expandable group boxes that are not part of an accordion, meaning they expand and collapse independently, allowing multiple group boxes to be open at the same time. However, this behavior would be inconsistent with all other forms that use accordion group boxes, so it should be used sparingly.

Managing Validation Errors using Accordion Group Boxes

When the form contains validation errors, the validation error navigator displays the number of validation errors in the form, along with buttons for navigating to the previous and next validation errors in the form.

Group boxes that contain validation errors are also shown in an error state to notify the user that it contains validation errors.

Start by connecting the validation error navigator to your Reactive form by binding the jhaForm property to your FormGroup. Define an event handler for the jhaErrorNavigation event. If your form utilizes custom form validators, bind an array of JhaCustomValidationMap elements to the jhaCustomValidationMappings property.

<jha-validation-error-navigator [jhaForm]="editForm" (jhaErrorNavigation)="goToFormControl($event)"
    [jhaCustomValidationMappings]="customValidationMaps">
</jha-validation-error-navigator>

When the user presses the previous error or next error buttons in the validation error navigator, it fires the jhaErrorNavigation event, specifying the formControlName for that previous/next field with a validation error in your Reactive form.

Your event handler must:

• Identify which accordion group box this field is contained within.
• Automatically expand that accordion group box. This closes all other accordion group boxes in the form.
• Scroll that field into view.
• Set focus to that field.

Start by creating a method to determine which group box in the accordion the field is contained within. The method will accept one argument, the formControlName value passed to the event handler. Test against each group of names to determine the correct section of the accordion, then update the selected section id to open the correct group box.

public displaySectionForFieldId(formControlName: string) {
    if (formControlName === 'name' ||
        formControlName === 'ssn' ||
        formControlName === 'birthdate' ||
        formControlName === 'lastLogin' ||
        formControlName === 'grossIncome' ||
        formControlName === 'interestRate' ||
        formControlName === 'accountTypes') {
        this.selectedSectionId = 'CustomerInformation';
    } else if (formControlName === 'street' ||
        formControlName === 'city' ||
        formControlName === 'state' ||
        formControlName === 'zip' ||
        formControlName === 'county' ||
        formControlName === 'country' ||
        formControlName === 'addressType') {
        this.selectedSectionId = 'Address';
    } else if (formControlName === 'homePhone' ||
        formControlName === 'businessPhone' ||
        formControlName === 'mobilePhone' ||
        formControlName === 'email' ||
        formControlName === 'alerts') {
        this.selectedSectionId = 'ContactInformation';
    } else if (formControlName === 'comments') {
        this.selectedSectionId = 'Comments';
    }
}

Next create a method to get the correct element by its id. Once identified, test if the element has child input elements. Custom input components such as p-calendar, p-checkbox, etc will need to have focus set on the first child input.

If the element doesn’t have child input elements, it’s a standard html element and focus can be applied to it directly.

public focusField(formControlName: string) {
    const nextControl = document.getElementById('field-' + formControlName);
    if (nextControl.getElementsByTagName('input')[0]) {
        // If element has child inputs, set focus on the first child input
        nextControl.getElementsByTagName('input')[0].focus();
    } else {
        // This is a standard input, just set focus
        nextControl.focus();
    }
}

Have the event handler run both methods to expand the correct accordion group box and focus the desired input.

public goToFormControl(formControlName: string) {
    this.displaySectionForFieldId(formControlName);
    setTimeout(() => { this.focusField(formControlName); }, 100);
}

Next create a public property populated with any custom validators used in the form. Import the JhaCustomValidationMap class, then create an array with the name of the error thrown by the validator, followed by an array of the formControlName values of the fields that need to be addressed in the validation error.

import { JhaCustomValidationMap } from '@jkhy/responsive-ui-angular/jha-forms';

...

public customValidationMaps: JhaCustomValidationMap[] = [
    new JhaCustomValidationMap('countryAddressTypeMismatch', ['country', 'addressType'])
];

Lastly, you need to notify users of validation errors within group boxes, even if they are collapsed. To do this, the jhaContainsError property of each rui-group-box needs to be true when it contains an input with a validation error.

Begin by creating a method for each form control to test its validity.

private nameFieldHasError(): boolean {
    return (this.name.invalid && (this.name.dirty || this.name.touched));
}

Create a method for each group box, to run the test methods of each of the included form components.

public customerInformationSectionHasError(): boolean {
    const hasError: boolean =
    this.nameFieldHasError() ||
    this.ssnFieldHasError() ||
    this.birthdateFieldHasError() ||
    this.lastLoginFieldHasError() ||
    this.grossIncomeFieldHasError() ||
    this.interestRateFieldHasError() ||
    this.accountTypesFieldHasError();

    return hasError;
}

Finally, bind each rui-group-box containsError property to its associated method.

<rui-group-box titleText="Customer Information" [containsError]="customerInformationSectionHasError()" ...>

Angular wrapper development

Elements of a Large Form that uses Accordion Group Boxes

• Save/Cancel buttons in the display block toolbar
• A validation error navigator in the display block toolbar, for quickly identifying validation errors in the form and navigating between them
• A set of accordion group boxes, each of which contains one section of the form
  • Stack the accordion group boxes vertically, one on top of the next.
  • Display the form section name as the group box title.
  • The vertical nature of the stacked group boxes fits well with the vertical scrolling for the page.

You must also include a floating toolbar for the view that duplicates the Save/Cancel buttons and the validation error navigator. This ensures that the user always has access to these important navigation buttons and will always be able to tell if the form contains a validation error.

In order to navigate programmatically to the correct input, you’ll need to add an id attribute to the outer div for each form field based on its formControlName attribute. Add a ‘field-’ prefix to the formControlName value to calculate the field’s id value.

Example: Let’s say you have a “Home Phone” field in your form and its formControlName is “HomePhone”. Add an id to the outer div for this field with the value “field-HomePhone”.

<input id="field-name" formControlName="name" type="text" class="jha-form-control" />

Using accordion group boxes means that only one group box is visible at a time. This is typically desirable since it can help cut down on scrolling. If you find a case where the user needs to see fields from multiple group boxes at the same time, you should first see if it makes sense to combine those fields into the same group box without making that section too large. If that approach doesn’t work for your use case, it is technically possible to use expandable group boxes that are not part of an accordion, meaning they expand and collapse independently, allowing multiple group boxes to be open at the same time. However, this behavior would be inconsistent with all other forms that use accordion group boxes, so it should be used sparingly.

Managing Validation Errors using Accordion Group Boxes

When the form contains validation errors, the validation error navigator displays the number of validation errors in the form, along with buttons for navigating to the previous and next validation errors in the form.

Group boxes that contain validation errors are also shown in an error state to notify the user that it contains validation errors.

Start by connecting the validation error navigator to your Reactive form by binding the jhaForm property to your FormGroup. Define an event handler for the jhaErrorNavigation event. If your form utilizes custom form validators, bind an array of JhaCustomValidationMap elements to the jhaCustomValidationMappings property.

<jha-validation-error-navigator [jhaForm]="editForm" (jhaErrorNavigation)="goToFormControl($event)"
    [jhaCustomValidationMappings]="customValidationMaps">
</jha-validation-error-navigator>

When the user presses the previous error or next error buttons in the validation error navigator, it fires the jhaErrorNavigation event, specifying the formControlName for that previous/next field with a validation error in your Reactive form.

Your event handler must:

• Identify which accordion group box this field is contained within.
• Automatically expand that accordion group box. This closes all other accordion group boxes in the form.
• Scroll that field into view.
• Set focus to that field.

Start by creating a method to determine which group box in the accordion the field is contained within. The method will accept one argument, the formControlName value passed to the event handler. Test against each group of names to determine the correct section of the accordion, then update the selected section id to open the correct group box.

public displaySectionForFieldId(formControlName: string) {
    if (formControlName === 'name' ||
        formControlName === 'ssn' ||
        formControlName === 'birthdate' ||
        formControlName === 'lastLogin' ||
        formControlName === 'grossIncome' ||
        formControlName === 'interestRate' ||
        formControlName === 'accountTypes') {
        this.selectedSectionId = 'CustomerInformation';
    } else if (formControlName === 'street' ||
        formControlName === 'city' ||
        formControlName === 'state' ||
        formControlName === 'zip' ||
        formControlName === 'county' ||
        formControlName === 'country' ||
        formControlName === 'addressType') {
        this.selectedSectionId = 'Address';
    } else if (formControlName === 'homePhone' ||
        formControlName === 'businessPhone' ||
        formControlName === 'mobilePhone' ||
        formControlName === 'email' ||
        formControlName === 'alerts') {
        this.selectedSectionId = 'ContactInformation';
    } else if (formControlName === 'comments') {
        this.selectedSectionId = 'Comments';
    }
}

Next create a method to get the correct element by its id. Once identified, test if the element has child input elements. Custom input components such as p-calendar, p-checkbox, etc will need to have focus set on the first child input.

If the element doesn’t have child input elements, it’s a standard html element and focus can be applied to it directly.

public focusField(formControlName: string) {
    const nextControl = document.getElementById('field-' + formControlName);
    if (nextControl.getElementsByTagName('input')[0]) {
        // If element has child inputs, set focus on the first child input
        nextControl.getElementsByTagName('input')[0].focus();
    } else {
        // This is a standard input, just set focus
        nextControl.focus();
    }
}

Have the event handler run both methods to expand the correct accordion group box and focus the desired input.

public goToFormControl(formControlName: string) {
    this.displaySectionForFieldId(formControlName);
    setTimeout(() => { this.focusField(formControlName); }, 100);
}

Next create a public property populated with any custom validators used in the form. Import the JhaCustomValidationMap class, then create an array with the name of the error thrown by the validator, followed by an array of the formControlName values of the fields that need to be addressed in the validation error.

import { JhaCustomValidationMap } from '@jkhy/responsive-ui-angular/jha-forms';

...

public customValidationMaps: JhaCustomValidationMap[] = [
    new JhaCustomValidationMap('countryAddressTypeMismatch', ['country', 'addressType'])
];

Lastly, you need to notify users of validation errors within group boxes, even if they are collapsed. To do this, the jhaContainsError property of each jha-group-box needs to be true when it contains an input with a validation error.

Begin by creating a method for each form component to test its validity.

private nameFieldHasError(): boolean {
    return (this.name.invalid && (this.name.dirty || this.name.touched));
}

Create a method for each group box, to run the test methods of each of the included form components.

public customerInformationSectionHasError(): boolean {
    const hasError: boolean =
    this.nameFieldHasError() ||
    this.ssnFieldHasError() ||
    this.birthdateFieldHasError() ||
    this.lastLoginFieldHasError() ||
    this.grossIncomeFieldHasError() ||
    this.interestRateFieldHasError() ||
    this.accountTypesFieldHasError();

    return hasError;
}

Finally, bind each jha-group-box containsError property to its associated method.

<jha-group-box jhaTitle="Customer Information" [jhaContainsError]="customerInformationSectionHasError()" ...>

Design

Figma design

A large form that uses accordion group boxes includes the following elements:

• One display block
• Save/Cancel buttons in the display block toolbar
• A series of accordion group boxes laid out vertically.
  • Each group box contains one section of the form.
  • Display the name of the form section as the group box title.
  • This is an accordion, so only one of the group boxes can be expanded at a time.

Adobe XD design

A large form that uses accordion group boxes includes the following elements:

• One display block
• Save/Cancel buttons in the display block toolbar
• A series of accordion group boxes laid out vertically.
  • Each group box contains one section of the form.
  • Display the name of the form section as the group box title.
  • This is an accordion, so only one of the group boxes can be expanded at a time.