This document describes the toggle group component system in PatternFly Java. Toggle groups provide a set of controls that allow users to quickly switch between mutually exclusive options (single selection) or select multiple options simultaneously (multi-selection). They are typically used for filtering, view switching, or option selection in toolbars and control panels.
For form input components like checkboxes and radio buttons, see Form and Input Components. For dropdown-style selection components, see Menu and Selection Components.
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java1-253 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java1-242
The toggle group system consists of two primary classes that implement a container-item pattern:
| Component | Type | Purpose |
|---|---|---|
ToggleGroup | Container | Manages selection mode, state, and collection of items |
ToggleGroupItem | Item | Individual selectable button with text/icon |
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java62-65 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java59-66
Toggle groups support two selection modes defined by the SelectionMode enum:
In single selection mode (SelectionMode.single):
In multi-selection mode (SelectionMode.multi):
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java85-102 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java199-208
The ToggleGroup class serves as the container component that manages the collection of ToggleGroupItem instances.
The toggle group maintains state through several internal data structures:
| Field | Type | Purpose |
|---|---|---|
items | LinkedHashMap<String, ToggleGroupItem> | Ordered collection of items by identifier |
disabledSnapshot | HashMap<String, Boolean> | Preserves individual disabled states when group is disabled |
selectHandler | List<SelectHandler<ToggleGroupItem>> | Handlers for single selection events |
multiSelectHandler | List<MultiSelectHandler<ToggleGroup, ToggleGroupItem>> | Handlers for multi-selection events |
selectionMode | SelectionMode | Current selection mode (single or multi) |
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java77-83
Items are added via the add() method, which:
items map using its identifierAddItemHandler callbacksSources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java107-111
When a toggle group is disabled:
disabledSnapshotSources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java116-135
The selection methods follow a delegation pattern where simpler signatures delegate to more complex ones:
select(String identifier) - Selects an item by IDselect(String identifier, boolean selected) - Sets selection stateselect(String identifier, boolean selected, boolean fireEvent) - Controls event firingselect(ToggleGroupItem item, boolean selected, boolean fireEvent) - Core implementationSources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java182-210
The ToggleGroupItem class represents individual selectable items within a toggle group.
Each toggle group item consists of:
Each item maintains its own data context through the ComponentContext interface:
| Feature | Type | Purpose |
|---|---|---|
identifier | String | Unique identifier for the item |
data | Map<String, Object> | Key-value storage for custom data |
button | HTMLContainerBuilder<HTMLButtonElement> | Builder for the button element |
textElement | HTMLElement | Container for text content |
iconContainer | HTMLElement | Container for icon content |
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java81-85
The item supports three content configurations:
text(String text)icon(Element icon)iconAndText(Element icon, String text, IconPosition position)Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java114-143 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java219-241
Item selection state is managed through ARIA attributes and CSS modifiers:
The selection state is:
aria-pressed attribute on the button elementpf-m-selected CSS modifier classaria-pressed attribute valueSources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java210-217
The complete selection flow involves coordination between the item and its parent group:
For single selection mode, the group ensures only one item is selected:
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java195-203 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java199-208
For multi-selection mode, items are toggled independently:
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java204-206
Toggle groups support multiple event handler types following the standard PatternFly Java handler pattern.
| Handler Interface | Trigger | Parameters |
|---|---|---|
AddItemHandler<ToggleGroup, ToggleGroupItem> | Item added | group, item |
UpdateItemHandler<ToggleGroup, ToggleGroupItem> | Item updated | group, oldItem, newItem |
RemoveItemHandler<ToggleGroup, ToggleGroupItem> | Item removed | group, item |
SelectHandler<ToggleGroupItem> | Single selection changed | event, item, selected |
MultiSelectHandler<ToggleGroup, ToggleGroupItem> | Multi-selection changed | event, group, selectedItems |
Handlers are stored in lists and invoked via forEach:
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java150-173 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java206-209
The ToggleGroup implements the HasItems interface, providing standard collection management operations.
Additional convenience methods for selection querying:
| Method | Return Type | Description |
|---|---|---|
selectedItems() | List<ToggleGroupItem> | Returns all currently selected items |
unselect() | void | Deselects all items |
unselect(boolean fireEvent) | void | Deselects all items with optional event firing |
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java212-246 components/src/main/java/org/patternfly/component/HasItems.java42-206
Create a toggle group with mutually exclusive options:
Create a toggle group for multiple filter selections:
Create items with both icons and text:
Control selection state programmatically:
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java69-102 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java70-98
Toggle groups commonly appear within other container components:
| Container | Usage Pattern | Example |
|---|---|---|
Toolbar | View switching controls | Grid/list view toggles in toolbars |
ToolbarGroup | Grouped toolbar actions | Filter toggles grouped by category |
Panel | Panel header controls | Collapsible panel view options |
Card | Card header actions | Card display mode selection |
The toggle group follows standard component composition patterns, implementing BaseComponent and utilizing the component storage system for parent component lookup via lookupComponent().
Sources: components/src/main/java/org/patternfly/component/togglegroup/ToggleGroup.java62-65 components/src/main/java/org/patternfly/component/togglegroup/ToggleGroupItem.java199-201
Refresh this wiki