Examples
Basic
Single-item helper text at every status. Each status auto-renders a default icon when no
iconName is passed.
With custom icons
Pass iconName to override the default status icon with a Font Awesome / pficon glyph.
Multiple items
Compose many items inside one container by opening the
helper-text include's items slot and including
helper-text-item per row. Useful for password-requirement checklists, multi-field
validation summaries, etc.
- At least 8 characters
- Contains an uppercase letter
- Contains a number
- Contains a special character
Dynamic
pf-m-dynamic status-transition helper text — the live-validation shape across all five states.
Dynamic list
The same dynamic states as a requirements list (ul) — the password-rules shape.
- Fulfilled: At least 12 characters
- Fulfilled: Includes an uppercase letter
- Not met: Includes a number
Documentation
Container props
Parameters accepted by
{#include components/feedback/helper-text ... }...{/include}. Model mode: pass
helperText=<HelperText> built in Java instead — the Java tab on each example
shows the builder. The container has two shapes, discriminated by component —
single-item shortcut (component="div", default; the include body becomes the text of
one auto-wrapped item) or multi-item list (component="ul"; the body is passed through
verbatim and should contain helper-text-item includes with
component="li").
| Name | Type | Default | Description |
|---|---|---|---|
id
|
String | — |
DOM id on the container. Reference it from a form control's
aria-describedby to announce all items together.
|
| (content slot) | Slot | — |
Include body. In single-item shortcut mode (default), it becomes the text inside one auto-wrapped item. In
multi-item list mode (component="ul"), it's passed through verbatim — put one
or more helper-text-item includes here.
|
component
|
"div" | "ul"
|
"div"
|
Wrapping element. "ul" enables list semantics — emits
role="list" (defends against WebKit dropping the implicit role on
list-style: none) and switches the body to pass-through. Pair with
helper-text-item component="li" children.
|
ariaLabel
|
String | — |
Only emitted when component="ul"; labels the list for assistive tech.
|
variant / dynamic /
iconName
|
See item props | — |
Applied to the single item rendered by the single-item shortcut. Ignored when
component="ul" (set them on each
helper-text-item instead).
|
Item props
Parameters accepted by
{#include components/feedback/helper-text-item ... /}.
| Name | Type | Default | Description |
|---|---|---|---|
| * (content slot) | Slot | — | Body text of the item, passed as the include body. |
component
|
"div" | "li"
|
"div"
|
Wrapping element. Use "li" when this item is nested inside a
helper-text with component="ul".
|
variant
|
"indeterminate" | "warning" | "success" | "error"
|
— |
Applies pf-m-{variant} and auto-picks a default icon (fa:circle-check
for success, fa:triangle-exclamation for warning,
fa:circle-exclamation for error, fa:minus for
indeterminate).
|
dynamic
|
boolean |
false
|
Applies pf-m-dynamic for status transitions (PF v6 fades in the changed text +
icon).
|
iconName
|
String "set:slug"
|
Auto by status |
Override the default per-status icon. Same naming convention as the icon component (e.g.
fa:lightbulb, pficon:cluster).
|
id
|
String | — |
DOM id on the item element. Reference it from aria-describedby to announce a
specific item without the rest.
|
screenReaderText
|
String | — |
Screen-reader-only suffix (wrapped in pf-v6-screen-reader). Useful to announce
the variant explicitly when the icon alone isn't sufficient.
|
Divergence from PF React. PF exposes additional props we don't implement:
component (switch container/item to ul/li), isLiveRegion (add aria-live for dynamic
announcements), and aria-label on the container. They're not used anywhere in this
project yet — add when a real consumer needs them.
Usage
Single-item vs. multi-item. If you only need one helper-text row, pass the text as the include body
— the container wraps it as a single item with the variant and icon you supplied. If you need multiple rows (e.g. a
password-requirement checklist), add component="ul" to the container and put one
helper-text-item component="li" include per row in the body. Matches PF React's
<HelperText component="ul"> with
<HelperTextItem component="li"> children.
Default icons. Setting variant on an item without an
iconName auto-renders the matching status icon — success gets a check, warning gets a
triangle, error gets an x-circle, indeterminate gets a dash. Skip both variant and
iconName for plain informational text (no icon, default text color).
Wiring to a form field. Set id on the container, then reference it
from the input's aria-describedby:
<input aria-describedby="ht-username"> paired with
{#include components/feedback/helper-text id="ht-username" .../}. Screen readers
will announce the helper text together with the field's label.
Dynamic updates. When the helper text is updated by client-side validation (e.g. HTMX swap), set
dynamic=true on the item so PF's transition fades the change in. For announcements to
screen readers, you'd want isLiveRegion on the container — not implemented yet (see
divergence note above).