# @astrouxds/rux-icon

> Astro Web Component for Icons

Latest version **5.3.1** (published 2022-04-01) · SEE LICENSE IN LICENSE.md license · 0 weekly downloads

## Install

```sh
npm install @astrouxds/rux-icon
pnpm add @astrouxds/rux-icon
yarn add @astrouxds/rux-icon
bun add @astrouxds/rux-icon
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.3.1 |
| Published | 2022-04-01 |
| First published | 2018-05-22 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.md |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 455 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Rocket Communications |
| Maintainers | jacob-rocket, dmcalester, joel_perez, rocketmark, sasha-rocket |

## Links

- npm: https://www.npmjs.com/package/@astrouxds/rux-icon
- Repository: https://github.com/RocketCommunicationsInc/astro-components/src/master
- Homepage: https://www.astrouxds.com
- Issues: https://github.com/RocketCommunicationsInc/astro-components/issues
- npm.io page: https://npm.io/package/@astrouxds/rux-icon

## Dependencies (2)

- [lit-element](https://npm.io/package/lit-element.md) ^2.1.0
- [@webcomponents/webcomponentsjs](https://npm.io/package/@webcomponents/webcomponentsjs.md) ^2.2.10

## Recent versions

- 5.3.1 (latest) — 2022-04-01
- 4.0.0-0 (next) — 2019-05-21
- 5.3.0 — 2021-10-21
- 5.0.2 — 2021-06-28
- 5.0.1 — 2021-06-03
- 5.0.0 — 2021-02-01
- 4.0.3 — 2020-08-18
- 4.0.2 — 2020-05-12
- 4.0.1 — 2020-04-16
- 4.0.0 — 2019-08-06
- 4.0.0-alpha.2 — 2019-07-31
- 4.0.0-alpha.1 — 2019-07-31
- 3.0.2 — 2019-02-26
- 3.0.1 — 2019-01-24
- 3.0.0 — 2018-11-01
- … 6 more at https://npm.io/package/@astrouxds/rux-icon/versions

## README

# Icons

Display icons used in the Astro Design System

## Guidelines

-   [Astro UXDS: Icons and Symbols](https://astrouxds.com/ui-components/icons-and-symbols)

## Installation

`npm i -save @astrouxds/rux-icon`

## Web Components Usage

### 1. Installation

#### Install the Astro UXDS Icon package via Command Line (Preferred Method)

```sh
npm i --save @astrouxds/rux-icon
```

You may use Yarn, NPM, or your Node package manager of choice. The `--save` flag adds this component as a dependency in your `package.json` file.

#### **Alternatively**, download the [Astro Component Library](https://github.com/RocketCommunicationsInc/astro-components/) source to your project.

Via CLI:

```sh
git clone https://github.com/RocketCommunicationsInc/astro-components.git
```

Or, [download the Astro UXDS Components as a .zip](https://github.com/RocketCommunicationsInc/astro-components/archive/master.zip)

### 2. Import the Astro Icon Web Component

This example assumes you're using the NPM package in `node_modules`. Otherwise, import the component using the path to the Astro Components directory in your project.

```javascript
import { RuxIcon } from '@astrouxds/rux-icon/rux-icon.js'
```

### 3. Render the Astro Icon Web Component

Pass properties as attributes of the Astro Icon custom element:

```xml
<rux-icon icon="altitude" label="Altitude" color="#fff" ></rux-icon>
```

### Properties

| Property  | Type   | Default               | Required | Description                                                                                                                                                                                                                                                                                                                                                                           |
| --------- | ------ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon`    | String | `''`                  | Yes      | Displays an icon matching this string. For a [full list of available icons in the Astro default library, see the Icons section in Astro UXDS Guidelines](https://astrouxds.com/ui-components/icons-and-symbols)                                                                                                                                                                       |
| `label`   | String | `''`                  | Yes      | A descriptive label of the icon.                                                                                                                                                                                                                                                                                                                                                      |
| `library` | String | `'/icons/astro.svg'`  | No       | Defines the root-relative path for a specific icon library SVG for this icon. An icon library SVG document has individual icon elements identified by an `id` property on the node (usually on a `<g>` or `<path>`). If a value for `library` is not provided, the icon component assumes the Astro library SVG exists at the default path, and will look for the icon by `id` there. |
| `color`   | String | `'rgb(77, 172, 255)'` | No       | Applies a custom fill color as a valid HTML color string, e.g., hexadecimal, RGBA or HSL value.                                                                                                                                                                                                                                                                                       |
| `size`    | String | `'normal'`            | No       | Adjusts icon size, supported values are `extra-small` (16px), `small` (32px), `normal` (44px) and `large` (64px)                                                                                                                                                                                                                                                                      |

#### **Custom icons**

Access an external (non-Astro) icon library via the `library` attribute, which requires a root-relative path to an SVG file where the component's `icon` string attribute matches an element's `id`.

```xml
<rux-icon library="/icons/my-custom-icons.svg" icon="my-icon"></rux-icon>
```

In the SVG icon library file:

```svg
<svg>
	<defs>
		<g id="my-icon">...

```

## Revision History

##### **4.0**

-   Removed the `namespace:icon` pattern in favor of supporting multiple libraries, both default (Astro) and external, adding the `library` property (see [Astro 4 migration note](#astro-4-migration) below)
-   Replaced the DOM manipulation library for loading icons in favor of an HTML5 template TODO: add support for template outside of WebComponents when browser’s support shadowDOM piercing
-   Moved Astro Status Icons to their own package, `rux-status`
-   Replaced [Polymer 3](https://www.polymer-project.org) implementation with [LitElement](https://lit-element.polymer-project.org/) for improved speed and interoperability with JS Frameworks as well as simpler template declaration now available in vanilla JavaScript.
-   Extended icon set with Google Material Design icons. License: https://github.com/google/material-design-icons/blob/master/LICENSE

<a name="astro-4-migration">

## Important Astro 4 Migration Note:

Prior to Astro 4.0, the Astro UXDS Icon Component imported icons from a single SVG file where icons were identified by `id` under specific groups. In that method, icons were accessed via a namespaced value for the `icon` property, such as `"group-id:icon-id"`.

### Prior to Astro 4.0:

```xml
<rux-icon icon="default:settings"></rux-icon>

```

In Astro 4.0, these groups have been flattened, and each icon is now imported directly without any group prefix. If you would like to load another icon library SVG file, use the `library` property. You can easily namespace your own custom icons (e.g., `my-namespaced-prefix_settings`) and access those icons via the `icon` attribute.

### Astro 4.0 with default Astro icons:

```xml
<rux-icon icon="settings"></rux-icon>
```

### Astro 4.0 with custom icons:

```xml
<rux-icon library="/icons/my-namespaced-custom-icons.svg" icon="my-namespaced-prefix_settings"></rux-icon>
```

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