@icoset/icoset
v1.0.0
Published
Easily compose icon svg's for your apps.
Downloads
417
Readme
Icoset
Icoset is a node module that enables you to easily compose icon svg's for your apps. You would add this as a build step before running your app.
Install
yarn add @icoset/icoset
npm install @icoset/icoset
Use
icoset(array||object)
icoset()
takes in an object of options
or a collection of options
and outputs
a promise. The object resolved contains everything you need to consume svg's as
<symbols>
using the <use>
tag:
// example:
const icoset = require('icoset');
icoset({ directory: path.resolve('./icons') })
.then(results => console.log(results));
Outputs:
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="heart">...</symbol>
...
</svg>
Options
directory string
The directory where the .svg
's are hanging out.
- Required if
preset
is not defined. - Must be an absolute path.
preset function
A node module that points to a node_module
svg repo.
- Required if
directory
is not defined. - Function must return valid preset config.
icons array
By default, icoset will grab all the svg's it can find (default: icons: []
). However,
if we have access to a large icon set, we might not want them all. Specifying the
exact icons we want would greatly reduce output size.
String items:
Just specify file names (excluding the svg
extension) in the array:
icoset({
directory: '...',
icons: ['address-book', 'heart', 'check'],
})
Icoset will automatically find all icons that match.
Object items:
if you have a complicated svg directory, and need more control over what files to grab and how to name your icons, you can specify an object for each icon.
The object key is the final name of the icon, and the object value is the path to the file.
For example, if you're targeting: icons/regular/alarm.svg
, you would write
your config like this:
icoset({
directory: path.resolve(__dirname, 'icons'),
icons: [
{ alarm: 'regular/alarm.svg' },
],
});
Note:
The directory
property is still required - it will serve as the base path
for each object's value (partial path).
deepFind boolean
Deeply searches the directory for all .svg
s. Default is false
.
namePrependDirectory boolean
Prepend the directory structure to the icon name (only works if deepFind
is true
).
For example:
- say we have a deeply nested folder structure of
svgs/awesome/light/cool.svg
. - The
directory
we specify in the options issvgs
anddeepFind
istrue
. - If
namePrependDirectory
isfalse
, the icon name would be:cool.svg
. - If
namePrependDirectory
istrue
, then the outputted name would be:awesome-light-cool.svg
(the root directory is not included).
This is helpful if we had duplicate icon names, organized in different folders. A good
example of this is font awesome's svg structure (regular, light, etc). Using
namePrependDirectory
would output something like: light-address-book
and
regular-address-book
.
- Not Required.
- Default is
false
.
namePrependCustom string
Add a custom string to the beginning of all the icons names.
For example, if you specify my-icon
and the icon is address-book
, it will
output my-icon-address-book
(no need to append trailing dashes).
Note: If namePrependDirectory
and namePrependCustom
are both used,
then the following is the order that is enforced:
[namePrependCustom]-[namePrependDirectory]-[name]
- Not required
- Default is
null
nameRemovePattern string
Remove repetitive fluff from icon names.
For example, if all the icon names had icon-
in them, we can add this to
nameRemovePattern
to remove it from all the icons.
icoset({
nameRemovePattern: 'icon-',
icons: ['icon-weather'],
})
// outputs: 'weather'
- Not required.
- Default is
null
.
ignorePattern string
Don't add svg's to output if their name's match this pattern.
icoset({
ignorePattern: 'icon-',
})
// all icons that have `icon-` in them will be skipped.
- Not required.
- Default is
null
.
matchPattern string
Only add svg's to output if their name's match this pattern.
icoset({
matchPattern: 'icon-',
})
// only icons that have `icon-` in them will be added.
- Not required.
- Default is
null
.
svgoConfig object
Icoset uses svgo
to clean up the svg's. This option is a pass-through for the
svgo config argument.
Although svgo already has sensible defaults using preset-default
, you can
override anything you'd like here.
icoset({
svgoConfig: {
multipass: false,
plugins: [
'prefixIds',
],
},
});