ba-form-group-dropdown
ba-form-group-dropdown is used to show/hide a group of related form elements
Airframe
Web Components
React
React Native
Anatomy
Legend
Identifies the purpose of the grouped form inputs
Hint text
Provides additional guidance for the grouped form inputs
Summary toggle
Displays the current summary and opens or closes the group of form inputs
Expanded content
Contains the related form inputs shown when the dropdown is open
Design Documentation
This helps users understand the overall status of the inputs inside ba-form-group-dropdown.
The legend acts as a reference point within the form or page. If it changes, users may lose their position or have difficulty finding it again when they want to update it.
Use the input directly in the form instead of placing a single input in ba-form-group-dropdown.
This component appears over other content and may obstruct important information. It is easily dismissed by clicking outside it, so a programmatically triggered open state may flash or disappear before the user can interact with it.
If a nested input has an error, reflect it in the ba-form-group-dropdown error message using either the same message or a summary of multiple nested input errors.
Live Demo
<form>
<ba-form-group-dropdown
legend="Label Text"
hint-text="Hint text"
summary="Summary Text"
>
<p slot="error">Custom error</p>
<ba-input-text label="Form inputs go in here" name="inputName"></ba-input-text>
</ba-form-group-dropdown>
</form>Properties and attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
hintText |
hint-text |
Hint text to show above the input | string | undefined |
undefined |
inputWidth |
input-width |
The width of the input in characters | string | undefined |
undefined |
invalid |
invalid |
Show error state | boolean | undefined |
false |
legend(required) |
legend |
A legend for the dropdown | string |
undefined |
summary(required) |
summary |
Sets the summary | string |
undefined |
Permitted ARIA roles
- None
Slots
| Slot | Description | Permitted elements |
|---|---|---|
| Unnamed slot | Elements will render in the body of the component | <ba‑checkbox‑card>, <ba‑checkbox‑list>, <ba‑content>, <ba‑input>, <ba‑input‑date>, <ba‑input‑datepicker>, <ba‑input‑email>, <ba‑input‑number>, <ba‑input‑password>, <ba‑input‑phone‑number>, <ba‑input‑secure‑field>, <ba‑input‑stepper>, <ba‑input‑text>, <ba‑input‑textarea>, <ba‑input‑typeahead>, <ba‑input‑upload>, <ba‑radio‑group>, <ba‑select> |
"error" |
Validation message shown when show-error is present |
<p> |
Parent components
ba-form-group-dropdown can be slotted into:
Events
| Event | Description | Type |
|---|---|---|
baBlur |
Emitted when the input loses focus. | CustomEvent<void> |
baFocus |
Emitted when the input has focus. | CustomEvent<void> |
Properties and Attributes
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
hintText |
hint-text |
Hint text to show above the input | string | undefined |
undefined |
inputWidth |
input-width |
The width of the input in characters | string | undefined |
undefined |
invalid |
invalid |
Show error state | boolean | undefined |
false |
legend(required) |
legend |
A legend for the dropdown | string |
undefined |
summary(required) |
summary |
Sets the summary | string |
undefined |
Slots
| Slot | Description | Permitted elements |
|---|---|---|
| Unnamed slot | Elements will render in the body of the component | <ba‑checkbox‑card>, <ba‑checkbox‑list>, <ba‑content>, <ba‑input>, <ba‑input‑date>, <ba‑input‑datepicker>, <ba‑input‑email>, <ba‑input‑number>, <ba‑input‑password>, <ba‑input‑phone‑number>, <ba‑input‑secure‑field>, <ba‑input‑stepper>, <ba‑input‑text>, <ba‑input‑textarea>, <ba‑input‑typeahead>, <ba‑input‑upload>, <ba‑radio‑group>, <ba‑select> |
"error" |
Validation message shown when show-error is present |
<p> |
Note: <ba-input-stepper> fills the container rather than using its default maximum width.
Parent components
ba-form-group-dropdown can be slotted into:
Usage
ba-form-group-dropdown must always be placed in a form and consists of a legend, summary, and related form inputs that are shown when opened.
Basic usage
<form>
...
<ba-form-group-dropdown
legend="Label Text"
hint-text="Hint text"
summary="Summary Text"
>
<p slot="error">Custom error</p>
<!-- Form inputs to be shown when opened -->
</ba-form-group-dropdown>
...
</form>Guidelines
The legend and summary are used with the internal ARIA group role to help assistive technology users understand the relationship between the slotted inputs and their current value.
Further reading:
The summary uses aria-live="polite" so screen reader users are informed when its value changes.
In high contrast mode:
- The icon, legend, and summary text use the browser default text colour.
- A border is added around the expanded contents.
If a screen reader user navigates beyond the dropdown to text content, the dropdown remains visible because the component cannot detect focus on a non-interactive text node. On viewports at least 64rem wide, it closes automatically when the next element in the DOM is an interactive, tabbable element.
Keyboard navigation
State: Previous element in the DOM has focus
The disclosure button in ba-form-group-dropdown gets focus
State: The disclosure button has focus
Toggles ba-form-group-dropdown open or closed
Toggles ba-form-group-dropdown open or closed
Moves focus to the next tabbable element
State: ba-form-group-dropdown is open and the last focusable slotted element has focus on a viewport at least 64rem wide
Closes ba-form-group-dropdown and moves focus to the next focusable element on the page
State: ba-form-group-dropdown is open and its disclosure button has focus on a viewport at least 64rem wide
Closes ba-form-group-dropdown and moves focus to the previous focusable element on the page
State: ba-form-group-dropdown is open on a viewport at least 64rem wide
Closes ba-form-group-dropdown
Usage and accessibility checklist
Use this checklist to confirm the component has been configured and used correctly.
UX checklist
- ba-form-group-dropdown is used to group multiple related form inputs, not a single input
- ba-form-group-dropdown is placed within a form
- The summary is updated as nested inputs change so it reflects their current state
- The legend remains stable and is not dynamically changed
- The error message reflects errors in the nested inputs
- The dropdown is opened by a user action rather than programmatically
Accessibility checklist
- ba-form-group-dropdown has a visible, descriptive legend and summary
- ba-form-group-dropdown is keyboard operable and has a visible focus indicator
- The focus indicator has not been obscured on all sides of the disclosure button
- ba-form-group-dropdown has not been disabled
- Changes to the summary are announced to screen readers
These checks are handled by the component and do not need to be repeated each time it is used.
- ba-form-group-dropdown is operable using assistive technology
- Summary changes are announced to screen readers
- Has a visible focus indicator on all sides of the button
- Colour contrast for all states in all BAgel themes
- Animations respect users' reduced motion settings
- High contrast mode adjustments