FieldGroup

FieldGroup is a component that groups form fields together. Additionally, it provides a common label, helper text, and validation messages for all fields in the group.

Basic Usage

                                                
                                                <fieldset class="FieldGroup">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                </fieldset>

HTML Semantics

The FieldGroup component is a wrapper for form fields. Therefore, it uses the HTML <fieldset> element to group the fields together. The <legend> element is used to provide an accessible label for the group, while the <div> element with the FieldGroup__label class is used to provide a visible label. The reason for this duplication is that the <legend> element has very limited styling capabilities and is only used for accessibility purposes.

On the other hand, a plain <div> element is used to wrap the form fields instead of <ul> which might seem more appropriate at first. The reason for this is that the <fieldset> element already provides a semantic grouping for the fields. The <ul> element would only add additional complexity without providing any benefit.

⚠️ The FieldGroup component does not provide all necessary semantics and any styling to its child fields. It is up to the developer to configure the child fields correctly, including necessary attributes and CSS classes.

Required Fields

To render FieldGroup as required, add the FieldGroup__label--required modifier class to the FieldGroup__label element.

                                                
                                                <fieldset class="FieldGroup">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label FieldGroup__label--required" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                </fieldset>

⚠️ The FieldGroup__label element is only used to indicate visually that all fields in the group are required. The individual fields themselves need to be marked as required using the required attribute and the corresponding --required modifier class.

Hidden Label

Unlike from the real form fields like TextField or Select, the FieldGroup component does not provide a --hidden modifier class for its label. Because of its construction, you can simply hide the visual label by omitting it in the code.

                                                
                                                <fieldset class="FieldGroup">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <!-- div.FieldGroup__label is omitted -->
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                </fieldset>

⚠️ Remember the <legend> element should be always present to provide an accessible label for the group.

Helper Text

To render helper text, add a <div> element with the FieldGroup__helperText class.

                                                
                                                <fieldset class="FieldGroup" aria-describedby="fieldGroupHelperText">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                  <div id="fieldGroupHelperText" class="FieldGroup__helperText">Helper text</div>
                                                </fieldset>

👉 To improve the UX for users with assistive technologies, connect the helper text to the group using the aria-describedby attribute. This way, the helper text is announced when the group receives focus.

Fluid Width

To make the FieldGroup component fluid, add the FieldGroup--fluid modifier class to the <fieldset> element.

                                                
                                                <fieldset class="FieldGroup FieldGroup--fluid">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                </fieldset>

Disabled State

To disable all fields in the group, add the disabled attribute to the <fieldset> element.

⚠️ Additionally, the corresponding --disabled modifier classes need to be added to all child form components.

Why? While the disabled attribute on the <fieldset> element is already sufficient to disable the child inputs, you still need to add the --disabled modifier classes to all form fields to turn on the disabled styling on all elements.

                                                
                                                <fieldset class="FieldGroup" disabled>
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <div class="TextField TextField--disabled">
                                                      <label for="textField" class="TextField__label">Label</label>
                                                      <input type="text" id="textField" class="TextField__input" name="textField" placeholder="Placeholder" disabled />
                                                    </div>
                                                  </div>
                                                </fieldset>

Validation States

Validation states can be presented either by adding a CSS modifier class (FieldGroup--success, FieldGroup--warning, FieldGroup--danger), or by adding a JS interaction class when controlled by JavaScript (has-success, has-warning, has-danger). See Validation state dictionary.

                                                
                                                <fieldset class="FieldGroup FieldGroup--success" aria-describedby="fieldGroupSuccessValidationText">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                  <div id="fieldGroupSuccessValidationText" class="FieldGroup__validationText">Validation text</div>
                                                </fieldset>

To render validation text as a list, use <ul> element instead of <div>.

                                                
                                                <ul id="fieldGroupDangerValidationText" class="FieldGroup__validationText">
                                                  <li>First validation text</li>
                                                  <li>Second validation text</li>
                                                </ul>

👉 To improve the UX for users with assistive technologies, connect the validation text to the group using the aria-describedby attribute. This way, the validation text is announced when the group receives focus.

JavaScript-Controlled Validation Text

When implementing client-side form validation, use JS interaction state classes (has-success, has-warning, has-danger) on the wrapping <fieldset> element and render validation texts in a <div> with data-spirit-element="validation_text" attribute. This way your JS remains disconnected from CSS that may or may not be prefixed.

Remember this approach is only valid for vanilla JS implementation. React components mix CSS with JS by design and handle prefixes their own way.

                                                
                                                <fieldset class="FieldGroup FieldGroup--success" aria-describedby="fieldGroupSuccessValidationText">
                                                  <legend class="accessibility-hidden">Label</legend>
                                                  <div class="FieldGroup__label" aria-hidden="true">Label</div>
                                                  <div class="FieldGroup__fields">
                                                    <!-- Form fields… -->
                                                  </div>
                                                  <div id="fieldGroupSuccessValidationText" data-spirit-element="validation_text">Validation text</div>
                                                </fieldset>

👉 Consider using aria-live attribute on the validation text element to announce validation messages to screen readers.