Component Foundation

Relevant source files

• .editorconfig
• components/src/main/java/org/patternfly/component/button/Button.java
• components/src/main/java/org/patternfly/component/form/Checkbox.java
• components/src/main/java/org/patternfly/component/menu/MenuToggle.java
• components/src/main/java/org/patternfly/component/table/Cell.java
• components/src/main/java/org/patternfly/component/table/Table.java
• components/src/main/java/org/patternfly/component/table/Td.java
• components/src/main/java/org/patternfly/component/table/Th.java
• components/src/main/java/org/patternfly/component/table/Tr.java
• core/src/main/java/org/patternfly/core/Attributes.java

This document describes the foundational abstractions that underpin all PatternFly Java components. It covers BaseComponent, the generic class from which all components inherit; ComponentContext, the key-value storage mechanism; HasIdentifier, the interface for unique component identification; and the mixin-based interface pattern that enables behavioral composition without deep inheritance hierarchies.

For information about collection management patterns across container components, see Collection Management. For event handling patterns, see Event Handling Pattern.

---

Overview

PatternFly Java components follow a carefully designed architecture that prioritizes:

• Type safety: Generic type parameters ensure compile-time correctness
• Method chaining: Fluent API enables readable component construction
• Composition over inheritance: Small focused interfaces provide capabilities
• CSS encapsulation: Centralized CSS class management
• ARIA compliance: Built-in accessibility attribute support

The foundation consists of:

Abstraction	Role	Key Methods
BaseComponent	Base class for all components	css(), aria(), element(), that()
ComponentContext	Key-value storage interface	store(), has(), get()
HasIdentifier	Unique identification interface	identifier()
Mixin interfaces	Behavioral capabilities	disabled(), icon(), text(), etc.

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java72-80 components/src/main/java/org/patternfly/component/table/Tr.java85-89 components/src/main/java/org/patternfly/component/button/Button.java82-93

---

BaseComponent Class

BaseComponent is the abstract generic base class from which all PatternFly components inherit. It provides core functionality for DOM element management, CSS class manipulation, ARIA attribute management, and fluent API method chaining.

Generic Type Parameters

• E: The HTML element type (e.g., HTMLButtonElement, HTMLDivElement)
• B: The concrete component type for fluent method chaining (self-referential type)

This pattern enables type-safe method chaining where each method returns the concrete component type rather than BaseComponent.

Sources: components/src/main/java/org/patternfly/component/button/Button.java82 components/src/main/java/org/patternfly/component/menu/MenuToggle.java72

Core Capabilities

Sources: components/src/main/java/org/patternfly/component/button/Button.java150-161 components/src/main/java/org/patternfly/component/menu/MenuToggle.java149-181

Component Construction Pattern

All components follow a consistent construction pattern:

1. Factory methods create instances with appropriate element builders
2. Constructor initializes ComponentType, applies base CSS classes
3. storeComponent() registers the component for later lookup
4. Builder methods configure the component via method chaining
5. that() returns the concrete type for continued chaining

Example from Button:

components/src/main/java/org/patternfly/component/button/Button.java150-161

Example from MenuToggle:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java149-181

Sources: components/src/main/java/org/patternfly/component/button/Button.java95-139 components/src/main/java/org/patternfly/component/menu/MenuToggle.java84-130

The that() Pattern

The that() method is critical for type-safe method chaining. It returns this cast to the concrete component type B:

This enables fluent APIs where each method returns the concrete type:

Every component must implement that() to return its own type.

Sources: components/src/main/java/org/patternfly/component/button/Button.java315-317 components/src/main/java/org/patternfly/component/menu/MenuToggle.java381-383

Component Registration and Lookup

BaseComponent provides a component registry mechanism that allows components to be stored and retrieved from the DOM:

• storeComponent(): Stores the component instance in a static registry keyed by the element
• lookupComponent(): Retrieves the component instance from the DOM element or its ancestors
• lookupComponent(boolean): Lenient lookup that returns null if not found instead of throwing

This enables child components to access their parent containers without explicit reference passing.

Example usage in Td:

components/src/main/java/org/patternfly/component/table/Td.java99-103

Sources: components/src/main/java/org/patternfly/component/table/Td.java89-106 components/src/main/java/org/patternfly/component/table/Tr.java213

---

ComponentContext Interface

ComponentContext<E, B> provides a generic key-value storage mechanism attached to each component instance. This enables components to store arbitrary application data without requiring inheritance or field declarations.

Interface Definition

Implementation Pattern

Components implementing ComponentContext maintain a Map<String, Object> for storage:

components/src/main/java/org/patternfly/component/table/Tr.java124

The methods delegate to the map:

components/src/main/java/org/patternfly/component/table/Tr.java239-242 components/src/main/java/org/patternfly/component/table/Tr.java427-437

components/src/main/java/org/patternfly/component/table/Cell.java67-88

Usage Example

This pattern is commonly used in table rows to associate domain objects with UI rows without requiring custom subclasses.

Sources: components/src/main/java/org/patternfly/component/table/Tr.java85-89 components/src/main/java/org/patternfly/component/table/Cell.java34-37

---

HasIdentifier Interface

HasIdentifier<E, B> provides a standardized mechanism for component identification. Each component implementing this interface has a unique string identifier that enables lookup and reference.

Interface Definition

Implementation Pattern

Components store the identifier as a final field and register it in the DOM dataset:

components/src/main/java/org/patternfly/component/table/Tr.java122 components/src/main/java/org/patternfly/component/table/Tr.java135-148

components/src/main/java/org/patternfly/component/table/Cell.java39 components/src/main/java/org/patternfly/component/table/Cell.java42-47

Identifier Usage

Identifiers serve multiple purposes:

1. Uniqueness: Ensures each component can be uniquely identified
2. Lookup: Enables retrieval from collections via identifier
3. DOM association: Stored in data-pf-identifier for debugging
4. Reference: Allows selection/deselection by ID

Example usage in Table:

components/src/main/java/org/patternfly/component/table/Table.java226-236

Sources: components/src/main/java/org/patternfly/component/table/Tr.java85-89 components/src/main/java/org/patternfly/component/table/Cell.java34-37 components/src/main/java/org/patternfly/component/table/Table.java226-236

---

Mixin-Based Interface Pattern

PatternFly Java uses interface composition to provide component capabilities rather than deep inheritance hierarchies. Each interface represents a specific behavioral capability (e.g., disabled, icon, text) and provides default implementations where appropriate.

Common Mixin Interfaces

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java72-80 components/src/main/java/org/patternfly/component/button/Button.java82-93

Interface Composition Example

MenuToggle demonstrates extensive interface composition:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java72-80

This provides:

• ComponentIcon: Methods for adding/removing icons
• ComponentIconAndText: Combined icon and text placement
• Disabled: Enable/disable functionality
• ElementTextMethods: Text content management
• FullHeight / FullWidth: Size modifiers
• Primary / Secondary: Visual styling variants

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java72-80

Default Implementation Pattern

Many mixin interfaces provide default implementations that manipulate CSS classes:

Components simply implement the interface to gain the capability:

Sources: components/src/main/java/org/patternfly/component/button/Button.java82-93

The Disabled Interface Pattern

The Disabled interface demonstrates a more complex mixin with both CSS and DOM manipulation:

Components can override this to add additional behavior:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java276-290

This override:

1. Calls the default implementation via Disabled.super.disabled(disabled)
2. Adds component-specific logic (disable toggle element, action, checkbox, searchInput)
3. Returns this for continued chaining

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java276-290 components/src/main/java/org/patternfly/component/button/Button.java278-286

---

Mixin Interface Implementation Details

ComponentIcon Interface

Provides methods for managing icons in components:

Example implementation in Button:

components/src/main/java/org/patternfly/component/button/Button.java183-195

Sources: components/src/main/java/org/patternfly/component/button/Button.java183-195

ComponentIconAndText Interface

Combines icon and text with positional control:

Example implementation in Button with position handling:

components/src/main/java/org/patternfly/component/button/Button.java197-213

Sources: components/src/main/java/org/patternfly/component/button/Button.java197-213

HasValue Interface

Provides typed value management:

Example implementation in Checkbox:

components/src/main/java/org/patternfly/component/form/Checkbox.java62-66 components/src/main/java/org/patternfly/component/form/Checkbox.java232-235

Sources: components/src/main/java/org/patternfly/component/form/Checkbox.java62-66

---

Element Management Architecture

Element Delegation Pattern

Components manage internal DOM structure while exposing the root element. Child elements are created lazily and cached:

components/src/main/java/org/patternfly/component/button/Button.java342-354

This pattern:

1. Checks if child element exists
2. Creates and caches it if needed
3. Returns the cached instance

Sources: components/src/main/java/org/patternfly/component/button/Button.java342-354

The add() Method Override Pattern

Components often override add() methods to control where child elements are inserted:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java189-197

This ensures avatars are inserted in the correct container with proper CSS classes, rather than simply appended to the root element.

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java189-197 components/src/main/java/org/patternfly/component/menu/MenuToggle.java203-212

Text Content Management

Text content is managed through dedicated container elements:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java321-344

This approach:

1. Creates text container on first call
2. Inserts it in the correct position
3. Updates textContent on subsequent calls

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java321-344

---

CSS and ARIA Management

CSS Class Application

BaseComponent provides several methods for CSS class management:

• css(String...): Adds one or more CSS classes
• classList(): Returns the DOMTokenList for direct manipulation
• toggle(String, boolean): Conditionally adds/removes a class

Example usage:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java315-318

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java315-318

ARIA Attribute Management

Components use aria() methods to set ARIA attributes:

components/src/main/java/org/patternfly/component/menu/MenuToggle.java387-390

Common patterns:

• aria(Aria.expanded, boolean): For expandable components
• aria(Aria.label, String): For accessible labels
• aria(Aria.disabled, boolean): For disabled state
• aria(Aria.level, int): For hierarchical components

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggle.java387-390 components/src/main/java/org/patternfly/component/table/Tr.java274-308

Static Attributes

Common HTML attributes are defined in the Attributes interface:

core/src/main/java/org/patternfly/core/Attributes.java18-26

Sources: core/src/main/java/org/patternfly/core/Attributes.java18-26

---

Component Type System

Type Parameter Examples

Component	E Parameter	B Parameter
Button	HTMLElement	Button
MenuToggle	HTMLElement	MenuToggle
Table	HTMLTableElement	Table
Tr	HTMLTableRowElement	Tr
Checkbox	HTMLElement	Checkbox

Sources: components/src/main/java/org/patternfly/component/button/Button.java82 components/src/main/java/org/patternfly/component/menu/MenuToggle.java72 components/src/main/java/org/patternfly/component/table/Table.java62

---

Summary

The PatternFly Java component foundation provides:

1. BaseComponent<E, B>: Generic base class with element management, CSS manipulation, ARIA support, and fluent API
2. ComponentContext<E, B>: Key-value storage for attaching application data to components
3. HasIdentifier<E, B>: Unique identification mechanism for component lookup
4. Mixin interfaces: Composable behavioral capabilities via interface implementation
5. Type-safe method chaining: Via generic type parameters and the that() pattern
6. Component registry: For parent/child component communication
7. CSS and ARIA encapsulation: Centralized accessibility and styling management

This architecture enables:

• Components to be extended without deep inheritance
• Consistent APIs across all components
• Type safety throughout the fluent builder pattern
• Flexible behavioral composition via interface mixins
• Strong accessibility support by default

Sources: components/src/main/java/org/patternfly/component/button/Button.java components/src/main/java/org/patternfly/component/menu/MenuToggle.java components/src/main/java/org/patternfly/component/table/Table.java components/src/main/java/org/patternfly/component/table/Tr.java components/src/main/java/org/patternfly/component/form/Checkbox.java components/src/main/java/org/patternfly/component/table/Cell.java