Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shgysk8zer0/svg-use-symbols
An npm package for use with `<svg><use xlink:href=""></use></svg>`
https://github.com/shgysk8zer0/svg-use-symbols
svg svg-icons svg-sprites svg-symbols svg-use
Last synced: 4 months ago
JSON representation
An npm package for use with `<svg><use xlink:href=""></use></svg>`
- Host: GitHub
- URL: https://github.com/shgysk8zer0/svg-use-symbols
- Owner: shgysk8zer0
- License: mit
- Created: 2023-06-01T16:01:58.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-09-24T18:26:27.000Z (5 months ago)
- Last Synced: 2024-10-05T14:40:40.201Z (5 months ago)
- Topics: svg, svg-icons, svg-sprites, svg-symbols, svg-use
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@shgysk8zer0/svg-use-symbols
- Size: 251 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# @shgysk8zer0/svg-use-symbols
An npm package for use with ``
- - -
[](https://github.com/shgysk8zer0/svg-use-symbols/actions/workflows/codeql-analysis.yml)
[](https://github.com/shgysk8zer0/svg-use-symbols/blob/master/LICENSE)
[](https://github.com/shgysk8zer0/svg-use-symbols/commits/master)
[](https://github.com/shgysk8zer0/svg-use-symbols/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@shgysk8zer0/svg-use-symbols)
[](https://www.npmjs.com/package/@shgysk8zer0/svg-use-symbols)
[](https://github.com/shgysk8zer0)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
## Installation
```bash
npm i @shgysk8zer0/svg-use-symbols
```
## Supports
- Parsing from JSON and YAML files
- Creating multiple outputs by using an array of objects with `output` and `icons`
- Creating a single output file by using simple `id` and `path` object
- Creating from directories
- Fetching SVGs from URLs
- Migrating from `svg-sprite-generate` (converts CSV to JSON or YAML)
## Usage
### In HTML
This generates a series of ``s, which have the counterpart of `` for
using the icons on a webiste:
```html
```
### CLI
```
Usage: @shgysk8zer0/svg-use-symbols [options]
An npm package for use with ``
Options:
-V, --version output the version number
-c, --config [config] JSON or YAML config file
-d, --directory [directory] path to directory of SVGs
-e, --encoding [encoding] encoding (default: "utf8")
-f, --format [format] output format for migrating from CSV (default: "json")
-l, --list [list] comma separated list of SVGs
-m, --migrate [migrate] path to deprecated CSV config file
-o, --output [output] output file
-h, --help display help for command
```
```bash
svg-use-symbols -c path/to/config.yml -o img/icons.svg
svg use-symbols -d path/to/svgs/ -o img/icons.svg
svg-use-symbols -l icons/1.svg,icons/2.svg -o img/icons.svg
```
## Node
### Simple usage
```js
import { generateSymbols } from '@shgysk8zer0/svg-use-symbols';
await generateSymbols('config.json');
```
### Using `require()`
```js
const { generateSymbols } = require('@shgysk8zer0/svg-use-symbols');
// Top-level await not allowed
generateSymbols('config.json').catch(console.error);
```
### Advanced usage
```js
import { generateSymbol, writeSVG } from '@shgysk8zer0/svg-use-symbols';
const controller = new AbortController();
const config = {
"file-media": "octicons/file-media.svg",
"external": "https://example.com/external.svg",
};
const symbols = await Promise.all(
Object.entries(config).map(async ([id, path]) => {
try {
const symbol = await generateSymbol(id, path, { encoding: 'utf8', signal });
// Mutate symbol, perhaps?
return symbol;
} catch(err) {
console.error(err);
controller.abort();
}
})
);
await writeSVG('output.svg', symbols, { encoding: 'utf8' });
```
## Config files
This supports YAML, JSON, and *to a limited extent*, CSV. CSV is temporarily
offered for those migrating from `svg-sprite-generator` and will be removed in v2.
Please see the section on migrating.
For JSON and YAML, two different formats are supported:
```json
{
"id": "path/to/icon.svg",
"another": "https://example.com/path/to/icon.svg"
}
```
This will create ``s with `id` taken from the key and contents
from the SVG file at the given path/URL. This **MUST** have output (`-o` or `--output`)
set. This also applies for the temporarily supported CSV config files.
It may also use:
```json
[
{
"output": "path/to/output.svg",
"icons": {
"id": "path/to/icon.svg",
"another": "https://example.com/path/to/icon.svg"
}
},
{
"output": "path/to/output2.svg",
"icons": {
"id": "path/to/another-icon.svg",
"another": "https://example.com/path/to/another-icon.svg"
}
}
]
```
This will create output files `output.svg` and `output2.svg`, each containing
there respective ``s.
## Migrating from `svg-sprite-generator`
```bash
svg-use-symbols -m path/to/config.csv -o path/to/config.json
# Or
svg-use-symbols --migrate path/to/config.csv --format json --output /path/to/config.json
# Or
svg-use-symbols --migrate path/to/config.csv --format yaml --output /path/to/config.yaml
```