vite-svg-2-webfont
v3.4.0
Published
A vite plugin which generates a webfont out of svg icons
Downloads
4,441
Maintainers
Readme
vite-svg-2-webfont
A Vite Plugin that generates fonts from your SVG icons and allows you to use your icons in your HTML.
vite-svg-2-webfont
uses the webfonts-generator
package to create fonts in any format.
It also generates CSS files so that you can use your icons directly in your HTML, using CSS classes.
Installation
NPM
npm i -D vite-svg-2-webfont
YARN
yarn add -D vite-svg-2-webfont
PNPM
pnpm add -D vite-svg-2-webfont
Usage
Add the plugin to the vite.config.ts
with the wanted setup, and import the virtual module, to inject the icons CSS font to the bundle.
Vite config
Add the plugin to your vite configs plugin array.
// vite.config.ts
import { resolve } from 'path';
import { defineConfig } from 'vite';
import viteSvgToWebfont from 'vite-svg-2-webfont';
export default defineConfig({
plugins: [
viteSvgToWebfont({
context: resolve(__dirname, 'icons'),
}),
],
});
Import virtual module
Import the virtual module into the app
// main.ts
import 'virtual:vite-svg-2-webfont.css';
Add class-name to HTML element to use font
Use the font in templates with the icon font class and an icon class name.
The default font class name is .icon
and can be overriden by passing the baseSelector
configuration option.
Icon class names are derived from their .svg
file name, and prefixed with the value of classPrefix
which defaults to icon-
.
In the below example, the add
class would display the icon created from the file {context}/add.svg
<i class="icon icon-add"></i>
Configuration
The plugin has an API consisting of one required parameter and multiple optional parameters allowing to fully customize plugin setup.
context
- required
- type:
string
- description: A path that resolves to a directory, in which a glob pattern to find
svg
files will execute. The SVG files will be used to generate the icon font.
files
- type:
string
- description: An array of globs, of the SVG files to add into the webfont, from within the context
- default
['*.svg']
fontName
- type:
string
- description: Name of font and base name of font files.
- default
'iconfont'
dest
- type:
string
- description: Directory for generated font files.
- default
path.resolve(context, '..', 'artifacts')
- See webfonts-generator#dest
cssDest
- type:
string
- description: Path for generated CSS file.
- default
path.join(dest, fontName + '.css')
- See webfonts-generator#cssdest
cssTemplate
type:
string
description: Path of custom CSS template. Generator uses handlebars templates. Tht template receives options from
templateOptions
along with the following options:- fontName
- src
string
– Value of thesrc
property for@font-face
. - codepoints
object
- Codepoints of icons in hex format.
Paths of default templates are stored in the
webfontsGenerator.templates
object.webfontsGenerator.templates.css
– Default CSS template path. It generates classes with names based on values fromoptions.templateOptions
.webfontsGenerator.templates.scss
– Default SCSS template path. It generates mixinwebfont-icon
to add icon styles. It is safe to use multiple generated files with mixins together.
cssContext
cssFontsUrl
- type:
string
- description: Fonts path used in CSS file.
- default
cssDest
htmlDest
- type:
string
- description: Path for generated HTML file.
- default
path.join(dest, fontName + '.html')
- See webfonts-generator#htmldest
htmlTemplate
- type:
string
- description: HTML template path. Generator uses handlebars templates. Template receives options from
options.templateOptions
along with the following options:- fontName
- styles
string
– Styles generated with default CSS template. (cssFontsPath
is changed to relative path fromhtmlDest
todest
) - names
string[]
– Names of icons.
- See webfonts-generator#htmltemplate
ligature
- type:
boolean
- description: Enable or disable ligature function.
- default
true
- See webfonts-generator#ligature
normalize
- type:
boolean
- description: Normalize icons by scaling them to the height of the highest icon.
- default
false
- See svgicons2svgfont#optionsnormalize
round
- type:
number
- description: Setup SVG path rounding.
- default
10e12
- See svgicons2svgfont#optionsround
descent
- type:
number
- description: The font descent. It is useful to fix the font baseline yourself.
- default
0
- See svgicons2svgfont#optionsdescent
fixedWidth
- type:
boolean
- description: Creates a monospace font of the width of the largest input icon.
- default
false
- See svgicons2svgfont#optionsfixedwidth
fontHeight
- type:
number
- description: The outputted font height (defaults to the height of the highest input icon).
- See svgicons2svgfont#optionsfontheight
centerHorizontally
- type:
boolean
- description: Calculate the bounds of a glyph and center it horizontally.
- default
false
- See svgicons2svgfont#optionscenterhorizontally
generateFiles
- type:
boolean | string | string[]
- description: Sets the type of files to be saved to system during development.
- valid inputs:
true
Generate all file types.false
Generate no files.'html'
- Generate a HTML file'css'
- Generate CSS file'fonts'
- Generate font files (based on the types requested)
- default
false
types
- type:
string | string[]
- description: Font file types to generate. Possible values:
svg
ttf
woff
woff2
eot
- default
['eot', 'woff', 'woff2', 'ttf', 'svg']
- See webfonts-generator#types
codepoints
- type:
{ [key: string]: number }
- description: Specific code-points for certain icons. Icons without code-points will have code-points incremented from
startCodepoint
skipping duplicates. - See webfonts-generator#codepoints
classPrefix
- type:
string
- description: CSS class prefix for each of the generated icons.
- default
'icon-'
- See webfonts-generator#templateoptions
baseSelector
- type:
string
- description: CSS base selector to which the font will be applied.
- default
'.icon'
- See webfonts-generator#templateoptions
formatOptions
- type:
{ [format in 'svg' | 'ttf' | 'woff2' | 'woff' | 'eot']?: unknown };
- description: Specific per format arbitrary options to pass to the generator. Format and matching generator:
- svg - svgicons2svgfont.
- ttf - svg2ttf.
- woff2 - ttf2woff2.
- woff - ttf2woff.
- eot - ttf2eot.
- See webfonts-generator#formatoptions
moduleId
- type:
string
- description: Virtual module id which is used by Vite to import the plugin artifacts. E.g. the default value is "vite-svg-2-webfont.css" so "virtual:vite-svg-2-webfont.css" should be imported.
- default
'vite-svg-2-webfont.css'
inline
- type:
boolean
- description: Inline font assets in CSS using base64 encoding.
- default
false
allowWriteFilesInBuild
- type:
boolean
- description: Allow outputting assets (HTML, CSS, and Fonts) during build. see
- default
false
Public API
The plugin exposes a public API that can be used inside another plugins using Rollup inter-plugin communication mechanism.
Currently available methods:
getGeneratedWebfonts
- returns:
Array<{ type: 'svg' | 'ttf' | 'woff2' | 'woff' | 'eot', href: string }>
- description
type
- a font format generated by a pluginhref
- a path to a generated font
- This repo contains the usage example.