The form group groups multiple form elements, such as text fields, radio buttons or checkboxes, together in a container and provides a shared aria label, hint or error for them.
Configurator
LiveForm group: orientation, sizing, gap, hint and error message for all fields
VornameNachname
HTML
<oc-form-group-v1 orientation="horizontal" flex-behavior="grow" gap="var(--oc-base-dimension-8)" hint="Bitte gib deinen Namen so an wie im Personalausweis." oc-aria-label="Name"><oc-text-field-v1 autocomplete="given-name" style="width:10rem;min-width:0">Vorname</oc-text-field-v1><oc-text-field-v1 autocomplete="family-name" style="width:10rem;min-width:0">Nachname</oc-text-field-v1></oc-form-group-v1>
Usage
Variants
You can use form group with the following form components:
You can optionally extend the form group with a error or a hint. The hint helps the user filling out the form group correctly and provides further context. The error is shown additionally above the hint if the user made a wrong input. It helps the user understanding the mistake and fixing the input.
Hint
VornameNachname
Error and hint
VornameNachname
Liveerror and hintHTML
<p class="demo-label">Hint</p>
<oc-form-group-v1 orientation="horizontal" flex-behavior="grow" gap="var(--oc-base-dimension-8)" hint="Bitte gib deinen Namen an, wie im Personalausweis." oc-aria-label="Name">
<oc-text-field-v1>Vorname</oc-text-field-v1>
<oc-text-field-v1>Nachname</oc-text-field-v1>
</oc-form-group-v1>
<p class="demo-label">Error and hint</p>
<oc-form-group-v1 orientation="horizontal" flex-behavior="grow" gap="var(--oc-base-dimension-8)" hint="Bitte gib deinen Namen an, wie im Personalausweis." validation-message="Der eingegebene Text ist kein Name. Bitte korrigiere deine Eingabe." oc-aria-label="Name">
<oc-text-field-v1>Vorname</oc-text-field-v1>
<oc-text-field-v1>Nachname</oc-text-field-v1>
</oc-form-group-v1>
Behavior
Fitting
The components within the form group can either grow or shrink. For grow, the components will expand to fill the available space. Meanwhile, for shrink, the components will reduce their size to fit.
You can arrange the components within the form group either vertically or horizontally. Horizontal placement is particularly useful as it allows the hint and/or error to stretch across the full width. The gap can be customized. For text field for example you should at least use 8 px or for checkbox you should use at least 24px.
Don'tUse components which are not of the form cluster and not intended for use within the form group.
Accessibility
You can create one shared aria-label for the different components of the form group. This label is used by screen readers and should describe the form group's overall content or purpose. For example, for a form group that allows you to configure your birthday, you should create an Aria label such as "Geburtstag". The advantage is that the screen reader will not only read out the individual components, such as "Tag", "Monat" and "Jahr", but also summarise them as "Geburtstag".
Geburtstag
1
oc-aria-label="Geburtstag" names the whole group for screen readers
The form group component groups multiple form elements in a container and provides a label it.
It supports flexible layout options, validation messages, hint messages, and ARIA labels for accessibility.
Default variation
<oc-form-group-v1 class="${className}" oc-aria-label="Form Group" orientation="horizontal" flex-behavior="grow" style="--gap: var(--oc-base-dimension-8)"
><oc-text-field-v1>Text Field 1</oc-text-field-v1><oc-text-field-v1>Text Field 2</oc-text-field-v1></oc-form-group-v1
>${css}
Configuration
The form group component is configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the form group component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations.
Here, you can discover both common and specific variations that address different use cases.
To make the form group recognizable for screen readers, use the oc-aria-label attribute to provide clear and descriptive context information.
See the general accessibility documentation for guidance on using oc-aria-label, including how it works with link and masked link behavior.
Aria Description
The content of the form group can have additional information by using the hint attribute.
This helps users understand the purpose of the form group.
Validation
The form group can have a validation state by using the validation-message attribute.
The validation messages should be clear and concise.
They are automatically associated with the form elements and set the validation state of those elements.
Configuration (v1)
Form group configuration
Configure the Form group component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
<oc-form-group-v1 class="${className}" oc-aria-label="Form Group" orientation="horizontal" flex-behavior="grow" style="--gap: var(--oc-base-dimension-8)"
><oc-text-field-v1>Text Field 1</oc-text-field-v1><oc-text-field-v1>Text Field 2</oc-text-field-v1></oc-form-group-v1
>${css}
Interactive configurator (Storybook controls); every option is listed in the API section of this file.
API v1
Form Group v1 API
API: <oc-form-group-v1> (FormGroupV1)
The Form Group component groups multiple form elements in a container and provides a label it.
It supports flexible layout options, validation messages, hint messages, and ARIA labels for accessibility.
Attributes / properties
Attribute
Type
Default
Required
Description
orientation
"horizontal" | "vertical"
undefined
no
Defines the orientation of the form group, determining the layout of its child elements.
hint
string
undefined
no
Sets and displays a hint message for the form group, providing details for all child elements.
validation-message
string
undefined
no
Sets and displays an error message for the form group, marking all child elements as invalid.
flex-behavior
"shrink" | "grow"
undefined
no
Determines whether the form group should shrink or grow its child elements.
If set to grow, the child elements will expand to fill the available space. If set to shrink, the child elements will reduce in size to fit.
This setting works best with a horizontal orientation.
gap
string
undefined
no
Sets the gap between child elements in the form group.
Also, can be set by using the --gap CSS variable.
oc-aria-label
string
no
Sets the ARIA label of the form group. This label is used by screen readers and should describe the overall content or purpose of the form group.
Slots
Slot
Required
Description
default
yes
Sets the content of the form group. Example: <oc-text-field-v1>Text Field 1</oc-text-field-v1> <oc-text-field-v1>Text Field 2</oc-text-field-v1>
Events
Event
Detail type
Description
oc-property-change
OcFormGroupV1Events["oc-property-change"]
Whenever a property value changes, this event triggers. Use this event to track all property changes within the component.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
CSS custom properties
Custom property
Default
Description
--gap
Sets the gap between child elements in the form group.
--column-gap
Sets the gap between columns in the form group.
--row-gap
Sets the gap between rows in the form group.
Variations (v1)
Variations
Listed below are the most common variations of the form group component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.