Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dulnan/nuxt-svg-icon-sprite
Automatically generate SVG <use> sprite for icons and illustrations
https://github.com/dulnan/nuxt-svg-icon-sprite
Last synced: 3 months ago
JSON representation
Automatically generate SVG <use> sprite for icons and illustrations
- Host: GitHub
- URL: https://github.com/dulnan/nuxt-svg-icon-sprite
- Owner: dulnan
- License: mit
- Created: 2023-02-06T08:00:55.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-25T14:46:50.000Z (5 months ago)
- Last Synced: 2024-10-10T17:41:16.249Z (3 months ago)
- Language: TypeScript
- Size: 843 KB
- Stars: 1
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Nuxt SVG Icon Sprite
Easy and performant way to use SVG icons in your Nuxt 3 app.
Automatically creates [SVG ``
sprites](https://www.sitepoint.com/use-svg-image-sprites/) during build and
provides components and composables to use symbols.
- Aggregate all SVG files into a one or more sprite files
- Reduce bundle size and SSR rendered page size
- Full HMR support
- Provides `` component to render `` with ``
- Loads the sprite.svg from URL (/_nuxt/sprite.svg)
- Typescript type checking for available symbols
## Install
```bash
npm install --save nuxt-svg-icon-sprite
```
```typescript
export default defineNuxtConfig({
modules: ['nuxt-svg-icon-sprite'],
svgIconSprite: {
sprites: {
default: {
importPatterns: ['./assets/icons/**/*.svg'],
},
},
},
})
```
## Usage
Place the icons in the folder defined in nuxt.config.ts, by default it's
`./assets/icons`. The name of the SVG files is used to determine the symbol
name.
**NOTE: Per sprite each symbol must have an unique name!**
So, if you have a file in `./assets/icons/user.svg` the sprite will contain a
`` with id `user`.
You can now use the symbol using the provided component:
```vue
```
This will render the following markup:
```html
```
The symbol is referenced from the sprite via URL.
## Multiple Sprites
If you have a lot of icons it might make sense to split them into separate
sprites.
A typical example would be to have SVGs that appear on every page (navbar,
logo, footer, etc.) in the "default" sprite and put page-specific SVGs in
separate sprites.
To create an additional sprite just define a new property on the `sprites`
config object:
```typescript
export default defineNuxtConfig({
modules: ['nuxt-svg-icon-sprite'],
svgIconSprite: {
sprites: {
default: {
importPatterns: ['./assets/icons/**/*.svg'],
},
dashboard: {
importPatterns: ['./assets/icons-dashboard/**/*.svg'],
},
},
},
})
```
Assuming you have this file `~/assets/icons-dashboard/billing.svg`, you can
reference it like this:
```vue
```
The symbol name is prefixed by the name of the sprite (e.g. the key used in the
`sprites` config). The `default` sprite is always unprefixed.
## `` component
In addition to the `name` prop you can also optionally pass the `noWrapper`
prop to only render the `` tag:
```vue
```
This will render the following markup:
```html
```
This is useful if you want to render multiple symbols in one `` tag.
You may also use the `inline` prop on the `` component to render the SVG content directly instead of rendering the `` tag.
## `useSpriteData()` composable
Get information about the generated sprites and their symbols during runtime.
Useful if you want to render a list of all symbols in a styleguide:
```vue
const { symbols } = useSpriteData()
```
## Full Module Options
```typescript
import { optimize } from 'svgo'
export default defineNuxtConfig({
modules: ['nuxt-svg-icon-sprite'],
svgIconSprite: {
sprites: {
default: {
importPatterns: ['./assets/icons/**/*.svg'],
// Directly provide symbol SVG by path.
// These are added after the auto imports defined in the
// `importPatterns`.
symbolFiles: {
email: '~/node_modules/some_package/assets/icons/email.svg'
},
processSvg(markup: string, filePath: string) {
// Executed for each loaded file.
// Do something with the markup, e.g. execute SVGO or do some string
// replacements.
return optimize(markup).data
},
processSymbol(symbol, filePath) {
// Add attributes to the parsed symbol.
symbol.attributes.width = '24'
symbol.attributes.height = '24'
symbol.attributes.viewBox = '0 0 24 24'
// Afterwards the parsed symbol is converted to markup.
return symbol
},
processSprite(markup, name) {
// Executed for each sprite right before its saved.
// Run SVGO or whatever you like.
// Markup contains:
//
// ...
// ...
//
return markup
}
},
},
},
})
```
The options are the same for each `key` in `sprites`.
## TODO
- Provide more information about generated sprite via composable
- Provide option to inline sprite in SSR
- Option to directly provide symbols as markup
- Tests