# material-svg-atlas-plugin-webpack
This is a webpack plugin to generate an SVG atlas of select glyphs from the
[Material Symbols](https://fonts.google.com/icons) library.

## SVG Atlas
An SVG atlas improves websites by storing all icons and reusable graphics in
one place, allowing the browser to download them once and reuse them
everywhere.
By using an atlas, you get all your icons in one cached GET request, vs.
potentially hundreds of GET's for individual icons.

# Usage

## In Webpack
Define the plugin in your `webpack.config.js`.
A `referenceFile` and `filename` must be defined.

```js
const path = require("path")
const { MaterialSymbolsAtlasPlugin } = require("material-svg-atlas-plugin-webpack")

const iconsJsonPath = path.resolve(iconsPath, "material-symbols.json")
const iconsOutPath   = "icons/icons.svg"

module.exports = (env, argv) => {
    return {
        ...
        plugins: [
            new MaterialSymbolsAtlasPlugin({ referenceFile: iconsJsonPath, filename: iconsOutPath }),
        ],
    }
}
```

This will create an atlas at `filename` (`icons/icons.svg` in this case).

## Reference File
`referenceFile` refers to a `json` file containing the desired symbols.
Per-symbol parameters `style`, `wght`, `grad`, `fill`, and `opsz` can be defined.
It also allows for non-material icons to be included via using `path`.

```json
{ "refs": [
    { "path": "./sort_by_alpha_asc.svg",  "name": "sort_by_alpha_asc"  },
    { "path": "./sort_by_alpha_desc.svg", "name": "sort_by_alpha_desc" },
    { "symbol": "account_circle", "fill": true },
    { "symbol": "visibility_off", "fill": true },
    { "symbol": "warning", "style": "rounded" },
    { "symbol": "wysiwyg" }
]}
```

The symbols will be downloaded from the Material Symbols database at build time
and combined into an atlas using [svgo](https://svgo.dev/) and
[svg-sprite](https://github.com/svg-sprite/svg-sprite).

## Atlas Usage in HTML
To use the generated atlas, you just insert an `svg` containing a `use` into your html.
The `use` just needs to have the `href` attribute point to `{atlas}#{icon-id}`, e.g.:

```html
<svg class="white-icon">
    <use href="icons.svg#warning"></use>
</svg>
```

## Color
Color can be controlled through the `fill` attribute in CSS, e.g.:

```css
.white-icon {
    fill: white;
}
```

# TODO
* Version control for symbols (Material Symbols stores prior revisions of icons)
* Global settings for symbols (weight, opsz, etc)
* Support for [Vite](https://vite.dev/)