# Rivet Icons
Icons for the [Rivet Design System](https://rivet.iu.edu/).
[**View Demo**](https://rivet.iu.edu/icons/)
## Contents
1. [Quick start](#quick-start)
1. [Repo structure](#repo-structure)
1. [Install](#install)
1. [Getting started](#getting-started)
1. [Usage](#usage)
1. [Use the icon element](#use-the-icon-element)
1. [Use internal SVG symbols](#use-internal-svg-symbols)
1. [Use external SVG symbols](#use-external-svg-symbols)
1. [Use inline SVG](#use-inline-svg)
1. [Change icon color](#change-icon-color)
1. [Change icon size](#change-icon-size)
1. [Accessibility](#accessibility)
1. [Build a custom icon set](#build-a-custom-icon-set)
1. [API](#api)
1. [Request a new icon](#request-a-new-icon)
1. [Icon specifications](#icon-specifications)
1. [Run the docs site](#run-the-docs-site)
## Quick start
```html
Rivet icon example
```
## Repo structure
The following are some notable contents in this repo.
| Path | Description |
| --- | --- |
| `./dist` | Production files (CSS, HTML, JS, SVG). |
| `./src` | Source SVG files. |
## Install
Install the package to import production files or [build a custom icon set](#build-a-custom-icon-set).
```
npm install --save rivet-icons
```
This package can also be [browsed and linked to through UNPKG](https://unpkg.com/browse/rivet-icons/).
## Getting started
Rendering icons requires up to three pieces of content: CSS styles, SVG images, and optionally the Rivet Icon Element.
The easiest way to incorporate these parts is to link to them in the `` of the page.
```html
```
`rivet-icons.css` loads the required styles. `rivet-icons.js` appends the SVG images as internal [SVG symbols](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/symbol) in the ``. The [`defer` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer) means that the symbols file will be requested immediately, but it won't block rendering the rest of the page. `rivet-icon-element.js` loads the `` [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) as a convenience for using these icons, although it is optional. The [`type="module"` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-type) will cause the script to load just like using the `defer` attribute, but it also will be ignored by older browsers, such as Internet Explorer. In such a case, `` would look and behave just like an empty `` element.
If the build process allows, embed `rivet-icons.html` in the page in replacement of linking to `rivet-icons.js`. This avoids a use of JavaScript and saves a network request, at the expense of browser caching. This technique may be preferred if only a few icons are used on an independent page.
If [external SVG symbols are used](#use-external-svg-symbols), then `rivet-icons.svg` will be used instead of `rivet-icons.js` or `rivet-icons.html`.
## Usage
Once the icon files are loaded in the page, choose a way to use the icons.
1. [Use the icon element](#use-the-icon-element) (``).
1. [Use internal SVG symbols](#use-internal-svg-symbols).
1. [Use external SVG symbols](#use-external-svg-symbols).
1. [Use inline SVG](#use-inline-svg).
| Consideration | Element | Internal | External | Inline |
| --- | --- | --- | --- | --- |
| Works in latest browsers 1 | Yes | Yes | Yes | Yes |
| Works in Internet Explorer | No 2 | Yes | Maybe 3 | Yes |
| Requires JavaScript | Yes | No | Maybe 3 | No |
| Change icon color 4 | Yes | Yes | Yes | Yes |
| Change icon with CSS variables | Yes | No | No | No |
| Change icon with JavaScript | Yes | Yes | Yes | Yes |
| Can build custom icon set | Yes | Yes | Yes | Yes |
| Requires `rivet-icons.css` | Yes | Yes | Yes | Yes |
| Requires `rivet-icons.js` or `rivet-icons.html` | Yes | Yes | No | No |
| Requires `rivet-icons.svg` | No | No | Yes | No |
| Requires `rivet-icon-element.js` | Yes | No | No | No |
| Requires `rvt-icon-*.svg` or `rvt-icon-*.html` | No | No | No | Yes |
1. Latest browser versions of Chrome, Edge, Firefox, and Safari.
1. Internet Explorer does not support [custom elements](https://caniuse.com/custom-elementsv1) or [CSS variables](https://caniuse.com/css-variables).
1. Internet Explorer does not support [SVG external content](https://caniuse.com/mdn-svg_elements_use_external_uri). Use the [`svg4everybody` polyfill](https://github.com/jonathantneal/svg4everybody) to provide support.
1. Icons inherit their color from the CSS `color` property.
## Use the icon element
Render the icon in HTML.
```html
```
Use JavaScript to dynamically change the icon via the `name` attribute. This example uses JSX (React).
```jsx
const iconName = isFavorited ? 'heart-solid' : 'heart'
const icon = ()
```
Use CSS to dynamically change the icon via the `--rvt-icon` variable. Set its value to the CSS variable of the desired icon ("heart" is `var(--heart)`). In order to not pollute the global `:root` scope, icon variables are declared at the level of the `rvt-icon` element. That means, `--rvt-icon` should only be used on the `rvt-icon` element itself, not on an ancestor.
In this example, the button toggles the value of `aria-pressed` for screen reader users, while the icon updates between the solid heart and outlined heart for visual users. Change the icon color with the `color` property.
```html
```
```css
/* Do this. */
.favorite[aria-pressed="false"] .favorite__icon {
--rvt-icon: var(--heart);
}
.favorite[aria-pressed="true"] .favorite__icon {
--rvt-icon: var(--heart-solid);
color: red;
}
/* This won't work. */
.favorite[aria-pressed="false"] {
--rvt-icon: var(--heart);
}
.favorite[aria-pressed="true"] {
--rvt-icon: var(--heart-solid);
color: red;
}
```
CSS variable declarations always override the `name` attribute. In this case, the icon will render as `heart-solid`, not `heart`.
```html
```
```css
.heart-solid {
--rvt-icon: var(--heart-solid);
}
```
A "flash of unstyled content" happens when `` is used before the element definition is registered. This looks like the icon is briefly invisible, as if `visibility: hidden` is applied and suddenly removed. To avoid this, either place the `rivet-icons.html` or `rivet-icons.js` references before any use of ``, or wait to render content until after it registers with [`whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined).
```js
window.customElements.whenDefined('rvt-icon').then(() => {
render()
})
```
## Use internal SVG symbols
If not wanting to use ``, then render an icon with the following snippet. All `href` values reference the SVG symbol ID, in the format of `#rvt-icon-[name]`. With this method, the icon's color still changes with the CSS `color` property, but the icon itself cannot change with the `--rvt-icon` CSS variable.
```html
```
## Use external SVG symbols
If wanting to use `rivet-icons.svg` (rather than `rivet-icons.js` or `rivet-icons.html`), then add the path to the file, using a similar snippet as [internal SVG symbols](#use-internal-svg-symbols). Optionally include the [`svg4everybody`](https://github.com/jonathantneal/svg4everybody) polyfill to support Internet Explorer.
```html
```
## Use inline SVG
Icons can be placed inline in HTML. Copy and paste the contents of any inline icon (`rvt-icon-[name].html`) in the page.
```html
```
If the development environment allows it, prefer to import individual icons, rather than copying and pasting them. This example is how it could be done with React, with the right build configurations.
```jsx
import 'rivet-icons/dist/rivet-icons.css'
import heart from 'rivet-icons/dist/rvt-icon-heart.html'
const HeartIcon = (
)
```
Inline icons (`rvt-icon-[name].html`) are identical to the source icons (`rvt-icon-[name].svg`) except for changing some SVG attributes, given the context of use. [`xmlns` is not needed in HTML documents](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg). `width` and `height` are set with the `.rvt-icon` class. `aria-hidden` is added, as icons are decorative images.
## Change icon color
The icon color is inherited through the `color` property. It behaves just like text color.
```html
```
```css
.color-red {
color: red;
}
```
## Change icon size
Icons are sized at 16 square pixels, but padding and margin can be adjusted to fit into other contexts. For example, to increase the dimensions to 24 square pixels (while keeping the icon at its current scale), add `0.25rem` (`4px`) padding to the icon. This can be done with [Rivet spacing utility classes](https://rivet.iu.edu/components/layout/spacing/).
```html
```
## Accessibility
Icons are considered decorative images. They are hidden from screen readers via `