Skip to content

Commit d868e40

Browse files
dali327519294dali327519294
committed
docs(helper-text): add detailed documentation with examples and icon usage
1 parent 325d17b commit d868e40

File tree

2 files changed

+147
-16
lines changed

2 files changed

+147
-16
lines changed

‎elements/pf-helper-text/README.md‎

Lines changed: 121 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,141 @@
11
# `<pf-helper-text>`
22

3-
The **pf-helper-text** component provides contextual helper messages that indicate status, such as success, warning, error, or informational messages.
4-
It can include icons and supports custom content via slots.
3+
The **pf-helper-text** component provides contextual feedback messages for form fields or other UI elements.
4+
It visually communicates states such as success, warning, error, or informational messages.
5+
The component can display a default status icon or a fully custom icon provided through a slot or property.
6+
7+
Read more about dropdown in the [PatternFly Elements Dropdown
8+
documentation](https://patternflyelements.org/components/dropdown)
59

610
---
11+
## Installation
712

8-
## Usage
13+
Load `<pf-helper-text>` via CDN:
14+
15+
```html
16+
<script src="https://jspm.dev/@patternfly/elements/pf-helper-text/pf-helper-text.js"></script>
17+
18+
<script src="https://jspm.dev/@patternfly/elements/pf-icon/pf-icon.js"></script>
19+
```
20+
21+
Or, if you are using [NPM](https://npm.im), install it
922

10-
Import the component before using it:
23+
```bash
24+
npm install @patternfly/elements
25+
```
26+
27+
Then once installed, import it to your application:
1128

1229
```js
1330
import '@patternfly/elements/pf-helper-text/pf-helper-text.js';
1431
import '@patternfly/elements/pf-icon/pf-icon.js';
1532

16-
import '@patternfly/elements/pf-helper-text/pf-helper-text.js';
17-
import '@patternfly/elements/pf-icon/pf-icon.js';
33+
```
34+
35+
## Usage
36+
1837
```html
19-
<pf-helper-text status="warning">
20-
This is a warning helper text
38+
<script type="module">
39+
import '@patternfly/elements/pf-icon/pf-icon.js';
40+
import '@patternfly/elements/pf-helper-text/pf-helper-text.js';
41+
42+
// Optional: add FontAwesome icon set
43+
PfIcon.addIconSet('fas', (set, icon) => {
44+
return new URL(`@fortawesome/fontawesome-free/svgs/solid/${icon}.svg`, import.meta.url);
45+
});
46+
</script>
47+
48+
<pf-helper-text>
49+
This is default helper text
50+
</pf-helper-text>
51+
52+
<pf-helper-text status="indeterminate" icon="minus" icon-set="fas">
53+
This is indeterminate helper text
2154
</pf-helper-text>
2255
23-
<pf-helper-text status="error" icon="exclamation-triangle" icon-set="fas">
24-
This is an error helper text with icon
56+
<pf-helper-text status="warning" icon="exclamation-triangle" icon-set="fas">
57+
This is warning helper text
2558
</pf-helper-text>
2659
27-
<pf-helper-text status="success">
28-
<svg slot="icon" width="16" height="16" viewBox="0 0 16 16" fill="green" xmlns="http://www.w3.org/2000/svg">
29-
<path d="M6 10.8L3.2 8 2 9.2l4 4 8-8-1.2-1.2L6 10.8z"/>
30-
</svg>
31-
This is a success helper text with slotted icon
60+
<pf-helper-text status="success" icon="check-circle" icon-set="fas">
61+
This is success helper text
3262
</pf-helper-text>
3363
64+
<pf-helper-text status="error" icon="exclamation-circle" icon-set="fas">
65+
This is error helper text
66+
</pf-helper-text>
67+
68+
<style>
69+
pf-helper-text {
70+
display: block;
71+
margin: 1rem 0;
72+
font-family: var(--pf-global--FontFamily--sans-serif, Arial, sans-serif);
73+
}
74+
75+
pf-helper-text:not([status]) {
76+
color: var(--pf-global--Color--100, #151515);
77+
}
78+
pf-helper-text[status="indeterminate"] {
79+
color: var(--pf-global--Color--200, #6a6e73);
80+
}
81+
pf-helper-text[status="warning"] {
82+
color: var(--pf-global--warning-color--100, #f0ab00);
83+
}
84+
pf-helper-text[status="success"] {
85+
color: var(--pf-global--success-color--100, #3e8635);
86+
}
87+
pf-helper-text[status="error"] {
88+
color: var(--pf-global--danger-color--100, #c9190b);
89+
}
90+
91+
pf-helper-text [slot="icon"],
92+
pf-icon {
93+
fill: currentColor;
94+
}
95+
</style>
96+
3497
3598
```
99+
## Slots
100+
101+
| Name | Description |
102+
|------------|----------------------------------------------------------------------------------------|
103+
| `icon` | Optional named slot for providing a custom icon.<br>Overrides the default status icon. |
104+
| (default) | Default unnamed slot for the helper text content (text or other inline elements). |
105+
106+
Properties
107+
108+
|Name | Type | Default | Description|
109+
| ----- |-----------------------------------------------------|---------|--------------------------
110+
|status |'default','success','warning','error','indeterminate'|'default'| Defines the visual state of the helper text and determines which default icon is shown if no custom icon is provided.|
111+
|icon | string |undefined| Custom icon name to display. Overrides the default icon derived from status. Requires pf-icon to be imported.|
112+
|iconSet| string |undefined| Icon set to use when specifying a custom icon (e.g., 'fas').|
113+
114+
## Events
115+
116+
| Event Name | Description |
117+
| ------------ | -------------------------------------------------------------------------------- |
118+
| `icon-load` | Fired when a custom or default icon successfully loads. |
119+
| `icon-error` | Fired if the icon fails to load. The event’s `detail` contains the error object. |
120+
121+
## Default Icons by Status
122+
123+
| Status | Default Icon |
124+
| --------------- | ---------------------- |
125+
| `default` | *(none)* |
126+
| `indeterminate` | `minus-circle` |
127+
| `warning` | `exclamation-triangle` |
128+
| `success` | `circle-check` |
129+
| `error` | `exclamation-circle` |
130+
131+
## Notes
132+
133+
Providing a custom <slot name="icon"> overrides the default icon.
134+
135+
Icons are lazy-loaded (loading="lazy") to optimize performance.
136+
137+
The pf-icon element must be imported if using built-in icons.
138+
139+
The component emits icon-load and icon-error events to track icon state.
140+
141+

‎elements/pf-helper-text/demo/pf-helper-text.html‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,4 +68,29 @@
6868
pf-icon {
6969
fill: currentColor; /* צובע את הסמל בצבע הטקסט של ה-pf-helper-text */
7070
}
71-
</style>
71+
</style>
72+
73+
74+
| Name | Type | Default | Description |
75+
| --------- | ------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
76+
| `status` | `'default' \| 'success' \| 'warning' \| 'error' \| 'indeterminate'` | `'default'` | Defines the visual state of the helper text and determines which default icon (if any) will appear. |
77+
| `icon` | `string` | `undefined` | Custom icon name to display. Overrides the icon derived from `status`. Requires `pf-icon` to be imported. |
78+
| `iconSet` | `string` | `undefined` | Specifies the icon set to use when providing a custom `icon` (e.g. `'fas'`). |
79+
80+
| Name | Description |
81+
| ----------- | ---------------------------------------------------------------------------------------------------- |
82+
| `icon` | Optional named slot for providing a custom icon. When present, it overrides the default status icon. |
83+
| *(default)* | Default unnamed slot for the helper text’s main content (text or other inline elements). |
84+
85+
| Event Name | Description |
86+
| ------------ | -------------------------------------------------------------------------------- |
87+
| `icon-load` | Fired when a custom or default icon successfully loads. |
88+
| `icon-error` | Fired if the icon fails to load. The event’s `detail` contains the error object. |
89+
90+
| Status | Default Icon |
91+
| --------------- | ---------------------- |
92+
| `success` | `circle-check` |
93+
| `warning` | `exclamation-triangle` |
94+
| `error` | `exclamation-circle` |
95+
| `indeterminate` | `minus-circle` |
96+
| `default` | *(no icon)* |

0 commit comments

Comments
 (0)