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
<FieldGroup id="example-field-group" label="Label">
<!-- Form fields… -->
</FieldGroup>⚠️ 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.
⚠️ Remember the FieldGroup component is required to be used with content. Otherwise, it is useless. If it is used dynamically, make sure the FieldGroup component without content has been removed correctly.
👉 The FieldGroup component implements the <fieldset> HTML element. Read more about the advantages and limitations in the web implementation of FieldGroup.
Required Fields
To render FieldGroup as required, add the isRequired prop:
<FieldGroup id="example-field-group" label="Label" isRequired>
<!-- Form fields… -->
</FieldGroup>⚠️ The isRequired prop 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 isRequired prop.
Hidden Label
To visually hide the FieldGroup label, add the isLabelHidden prop:
<FieldGroup id="example-field-group" label="Label" isLabelHidden>
<!-- Form fields… -->
</FieldGroup>⚠️ Remember the label prop should be always set to provide an accessible label for the group.
Helper Text
To render helper text, add the helperText prop:
<FieldGroup helperText="Helper text" id="example-field-group" label="Label">
<!-- Form fields… -->
</FieldGroup>Fluid Width
To make the FieldGroup component fluid, add the isFluid prop:
<FieldGroup id="example-field-group" label="Label" isFluid>
<!-- Form fields… -->
</FieldGroup>Disabled State
To render FieldGroup as required, add the isDisabled prop:
<FieldGroup id="example-field-group" label="Label" isDisabled>
<!-- Form fields… -->
</FieldGroup>⚠️ Remember to also disable all fields in the group using the isDisabled prop.
👉 Read more about the disabled state in the web implementation of FieldGroup.
Validation States
Just like any other form component in Spirit, FieldGroup implements the Validation state dictionary.
Validation states can be presented either by adding the validationState attribute, or by adding a JS interaction class on the native HTML input when controlled by JavaScript (has-success, has-warning, has-danger).
When validated on server:
<FieldGroup
id="example-field-group"
label="Label"
validationState="success"
validationText="Success validation message"
/>API
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| form | string | null | ✕ | Parent form ID |
| helperText | string | null | ✕** | Custom helper text |
| id | string | — | ✓ | Group and label identification |
| isDisabled | bool | false | ✕ | If true, the group is disabled |
| isFluid | bool | false | ✕ | If true, the element spans to the full width of its parent |
| isLabelHidden | bool | false | ✕ | If true, label is hidden |
| isRequired | bool | false | ✕ | If true, the group is marked as required |
| label | string | null | ✕* | Label text |
| name | string | null | ✕ | Group name |
| UNSAFE_helperText | string | null | ✕** | Unescaped custom helper text (allows HTML) |
| UNSAFE_label | string | null | ✕* | Unescaped label text (allows HTML) |
| UNSAFE_validationText | [string | string[]] | null | ✕** | Unescaped validation text (allows HTML) |
| validationState | Validation dictionary | null | ✕ | Type of validation state |
| validationText | [string | string[]] | null | ✕** | Validation text |
(*) To keep the component accessible, a label is always required. You can use the label for simple text or UNSAFE_label for HTML content. (**) Props with and without UNSAFE_ prefix are mutually exclusive.
On top of the API options, the components accept additional attributes. If you need more control over the styling of a component, you can use style props and escape hatches.