Display icons used in the Astro Design System
npm i -save @astrouxds/rux-icon
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 source to your project.
Via CLI:
git clone https://github.com/RocketCommunicationsInc/astro-components.git
Or, download the Astro UXDS Components as a .zip
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.
import { RuxIcon } from '@astrouxds/rux-icon/rux-icon.js'
Pass properties as attributes of the Astro Icon custom element:
<rux-icon icon="altitude" label="Altitude" color="#fff" ></rux-icon>
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 |
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) |
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
.
<rux-icon library="/icons/my-custom-icons.svg" icon="my-icon"></rux-icon>
In the SVG icon library file:
<svg>
<defs>
<g id="my-icon">...
- Removed the
namespace:icon
pattern in favor of supporting multiple libraries, both default (Astro) and external, adding thelibrary
property (see Astro 4 migration note 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 implementation with LitElement 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
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"
.
<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.
<rux-icon icon="settings"></rux-icon>
<rux-icon library="/icons/my-namespaced-custom-icons.svg" icon="my-namespaced-prefix_settings"></rux-icon>