# @patternfly/pfe-icon

> Icon element for PatternFly Elements

Latest version **1.12.3** (published 2022-02-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @patternfly/pfe-icon
pnpm add @patternfly/pfe-icon
yarn add @patternfly/pfe-icon
bun add @patternfly/pfe-icon
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.12.3 |
| Published | 2022-02-01 |
| First published | 2019-01-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 323.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 394 |
| Author | Michael Clayton <mclayton@redhat.com> |
| Maintainers | ctrowbri, dgutride, dlabrecq, patternfly-build, jeff-phillips-18, mturley, mwcz, kylebuch8, realredallen, ktotten, evwilkin, schulj12, castastrophe, nicolethoen, heymp, zhawkins |
| Keywords | web-components, html |

## Links

- npm: https://www.npmjs.com/package/@patternfly/pfe-icon
- Repository: https://github.com/patternfly/patternfly-elements
- Homepage: https://github.com/patternfly/patternfly-elements#readme
- Issues: https://github.com/patternfly/patternfly-elements/issues
- npm.io page: https://npm.io/package/@patternfly/pfe-icon

## Dependencies (1)

- [@patternfly/pfelement](https://npm.io/package/@patternfly/pfelement.md) ^1.12.3

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 1.12.3 (latest) — 2022-02-01
- 2.0.0-next.6 (next) — 2022-12-09
- 2.0.0-next.5 — 2022-10-25
- 2.0.0-next.4 — 2022-08-23
- 2.0.0-next.3 — 2022-07-31
- 2.0.0-next.2 — 2022-04-18
- 2.0.0-next.1 — 2022-03-23
- 2.0.0-next.0 — 2022-02-23
- 1.12.2 — 2021-11-16
- 1.12.1 — 2021-11-16
- 1.12.0 — 2021-11-12
- 1.11.2 — 2021-09-29
- 1.11.1 — 2021-09-03
- 1.11.0 — 2021-08-18
- 1.10.1 — 2021-07-12
- … 62 more at https://npm.io/package/@patternfly/pfe-icon/versions

## README

# PatternFly Elements | Icon Element

## Usage

```html
<pfe-icon icon="rh-leaf"></pfe-icon>
```

## Slots

There are no slots, but if you wish to display some text when JS is disabled, you can put some text inside the pfe-icon tag.  For instance, when using a checkmark icon in a server status table, you may wish to display "success" if JS is disabled.

```html
<pfe-icon icon="rh-check-mark">success</pfe-icon>
```


## Attributes

| Name | Values | Description |
| --- | --- | --- |
| `icon` | `iconSet-iconName` | For example, `rh-leaf` loads a leaf icon from an icon set named "rh". |
| `size` | `sm` `md` `lg` `xl` `1x` `2x` `3x` `4x` | The default size is 1em, so icon size matches text size.  `2x`, etc, are multiples of font size.  `sm`, `md`, etc are fixed pixel-based sizes. |
| `color` | `base` `lightest` `lighter` `darker` `darkest` `complement` `accent` `accent` `critical` `important` `moderate` `success` `info` `default` | The color variant to use.  This draws from your theming layer to color the icon.  This will set icon color or background color (if `circled` is true). |
| `circled` | boolean attribute | Whether to draw a circular background behind the icon. |

## Icon sets

Icon sets are defined in detail in [this blog post][icon-sets].  The blog post should eventually be absorbed into the official documentation.

### Register a new icon set

To register a new icon set, choose a global namespace for that set and identify the path at which the SVGs for that set will be hosted.  Consider also the function needed to convert the icon name into the filename on that hosted location.  The `addIconSet` call accepts the namespace (as a string), the path to the SVGs (as a string), and a function for parsing the icon name into the filename.

```javascript
PfeIcon.addIconSet(
  "local",
  "./",
  function(name, iconSetName, iconSetPath) {
    var regex = new RegExp("^" + iconSetName + "-(.*)");
    var match = regex.exec(name);
    return iconSetPath + match[1] + ".svg";
  }
);
```

### Override the default icon sets

Out of the box, the default icon set (using the rh / web namespace) is hosted on [access.redhat.com](https://access.redhat.com). If you would like to override the `rh / web` namespace, you can add the following to a global variable named `PfeConfig`.

The config must be set _before_ the PfeIcon class is defined.

```javascript
window.PfeConfig = {
  IconSets: [
    {
      name: "web",
      path: "path/to/svg/directory", // Or https://hosted-icons.com/,
      resolveIconName: function(name, iconSetName, iconSetPath) { // Optional function to resolve icon paths.
        var regex = new RegExp("^" + iconSetName + "-(.*)");
        var match = regex.exec(name);
        return iconSetPath + match[1] + ".svg";
      }
    }
  ]
};
```

Now when `pfe-icon` is used, it will automatically reference the icon set defined in the config.

If you would like to opt out of any defaults so that you can dynamically add icon sets later using `PfeIcon.addIconSet()`, use the following:

```javascript
window.PfeConfig = {
  IconSets: []
};
```

### Updating an existing icon set

To updating an existing icon set, you use the same `addIconSet` function.  The first input which is the icon set namespace is required, as is the new path.  You can optionally pass in a new function for parsing the icon names into filenames.

```javascript
    PfeIcon.addIconSet("local", "https://hosted-icons.com/");
```

## Variables

There are several powerful ways to hook into and override default styles.

- Color: the `color` attribute is available to pull icon color from your theming layer.  For more fine-grained control, `--pfe-icon--color` is available to override the color of a specific icon or sets of icons and will be applied to the SVG.  [Examples][color-examples]
- Background color: the `color` attribute is available to pull background color from your theming layer.  For more fine-grained control, `--pfe-icon--BackgroundColor` is available to override the background color of a specific icon or sets of icons.  Be sure to set `--pfe-icon--context` to the appropriate context if you are setting the background-color or use the more fine-grained `--pfe-icon--color` to set a specific color on the SVG lines.

| Theme hook | Description | Default |
| -------------- | ----------- | ------- |
| `--pfe-icon--size` | The height and width of the icon | var(--pfe-theme--icon-size, 1em) |
| `--pfe-icon--spacing` | | var(--pfe-theme--container-spacer, 1rem) |
| `--pfe-icon--Padding` | Padding around the icon | 0 (when circled .5em) |
| `--pfe-icon--BackgroundColor` | Background color for when the icon is circled | transparent |
| `--pfe-icon--context` | Icon context when `--pfe-icon--BackgroundColor` is used | light |
| `--pfe-icon--BorderColor` | Border color when icon is circled | var(--pfe-icon--BackgroundColor, transparent) |
| `--pfe-icon--BorderWidth` | Thickness of the border when circled | var(--pfe-theme--ui--border-width, 1px) |
| `--pfe-icon--color` | Sets the color of the SVG lines | var(--pfe-icon--Color, var(--pfe-broadcasted--text, #3c3f42)) |
| *Deprecated* |
| `--pfe-icon--Color` | Deprecated | var(--pfe-broadcasted--text, #3c3f42) |

## Test

    npm test

## Build

    npm run build

## Demo

From the PFElements root directory, run:

    npm start

## Code style

All PFElements use [Prettier][prettier] to auto-format JS and JSON. The style rules get applied when you commit a change. If you choose to, you can [integrate your editor][prettier-ed] with Prettier to have the style rules applied on every save.

[prettier]: https://github.com/prettier/prettier/
[prettier-ed]: https://prettier.io/docs/en/editors.html
[blog]: https://clayto.com/2019/07/web-component-icons/index.html
[icon-sets]: https://clayto.com/2019/07/web-component-icons/index.html#icon-sets
[color-examples]: https://clayto.com/2019/07/web-component-icons/index.html#setting-icon-colors

---
_Source: https://npm.io/package/@patternfly/pfe-icon · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._