diff options
| -rw-r--r-- | README.md | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..9af422a --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# 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/) |