charm-icons
v0.18.0
Published
Charming Open Source vector icons.
Downloads
237
Readme
Charm Icons
Charming Open Source vector icons.
charm-icons is a (growing!) set of MIT Licensed vector icons primarily designed for the 16x16 pixel grid. They are designed to be simple and flexible.
Demo / Preview
You can take a look at the icons on CodePen or have a quick look below:
You can also look at the icons on icones.
Contents
Inspiration / Motivation
charm-icons takes inspiration from the following icon sets but tries to differ in key aspects.
- Octicons
- While Octicons have 16px variants designed for the 16x16 pixel grid, it does not use the
stroke-widthproperty, unlikecharm.- Thus,
charmallows for more customisation, and the icons tend to be smaller in file size.
- Thus,
- While Octicons have 16px variants designed for the 16x16 pixel grid, it does not use the
- Lucide / Feather
- Lucide Icons are primarily designed for 24x24 pixel resolution whereas
charmaims to look best at 16x16 pixel resolution.- For this reason,
charmmay work quite well alongside Lucide (be wary of design differences!).
- For this reason,
- Lucide Icons are primarily designed for 24x24 pixel resolution whereas
charm-icons is also built to be fully treeshakable with ESModules.
Installation
NPM (Recommended)
You can install via npm:
npm install charm-icons
# or
yarn add charm-iconsCDN
Note: The CDN version contains every icon - likely more than you will use. NPM installation is recommended so you can treeshake only the icons you need.
Testing / Experimentation
<script src="https://unpkg.com/charm-icons@latest/dist/umd/charm.js"></script>Minified
<script src="https://unpkg.com/charm-icons@latest"></script>Iconify
charm is available via iconify.
Iconify has component libraries for React, Vue, Svelte and Ember.
Usage
You may use the SVG files (found here) however you please. If you are using them in a javascript project, charm-icons provides a basic API for handling them.
Following are some examples of using the API to insert an icon into your webpage:
With ESModules (Recommended)
Your html will look like this:
<i data-charm="heart" class="my-class"></i>
<i data-charm="face-smile" class="my-class"></i>
<i data-charm="thumb-up" class="my-class"></i>Your javascript will look like one of the following:
Treeshaking (Recommended)
// Include the icons you need.
import { placeIcons, Heart, FaceSmile, ThumbUp } from 'charm-icons';
// Tell `placeIcons()` to replace them.
placeIcons({
icons: {
Heart,
FaceSmile,
ThumbUp,
},
});All icons
// This will still bundle any unused icons.
import { placeIcons, icons } from 'charm-icons';
placeIcons({ icons: icons });With CDN
<!DOCTYPE html>
<body>
<i data-charm="flame" class="my-class"></i>
<script src="https://unpkg.com/charm-icons@latest"></script>
<script>
charm.placeIcons({ icons: charm.icons });
</script>
</body>Using custom icons with the API
See this codepen demo for a working demo of this section.
You can use any icons you like with the API, provided the icon is an object with the following attributes:
| Attribute name | Type | Description |
|----------------|------------|--------------------------------------------|
| name | string | The name of the icon in kebab-case |
| paths | string | The svg content |
| keywords | [string] | A list of relevant keywords (may be empty) |
For example, let's make our own test icon, a copy of conical-flask with a different name:
<body>
<div>
<i data-charm="test"></i>
</div>
</body>const Test = {
name: 'test',
paths: '<path d="m4.75 1.75h6.5m-6.5 8h6.5m-5.5-7.5v4.5l-4 7.5h12.5l-4-7.5v-4.5"/>',
keywords: ['beaker', 'development', 'experimental', 'lab', 'science', 'study'],
};You can then pass the new icon to placeIcons():
charm.placeIcons({ icons: {Test} });API reference
charm.placeIcons({ icons = {}, attrs = {}, replaceAttr = 'data-charm' })
Replaces all elements with the replaceAttr attribute with the respective icon.
Parameters
icons- List of icons that you are using, e.g
{ AtSign, Tick } - If you want to use all icons, then use
icons
- List of icons that you are using, e.g
attrs- Attributes to add to every icon replaced by
placeIcone.g{ class: "my-class my-other-class"}
- Attributes to add to every icon replaced by
replaceAttrplaceIconsreplaces all elements with thereplaceAttr(by default'data-charm') attribute with the icon specified, e.gdata-charm="at-sign".- Note: here you use
kebab-casefor the icon name (at-signinstead ofAtSign)
- Note: here you use
charm.toSvg(icon, attrs = {})
Converts an icon object to an SVG string.
Parameters
icon- Icon object to convert.
attrs- (Optional) attributes to add to the SVG root.
charm.toElement(icon, attrs = {})
Converts an icon object to an SVG HTMLElement
Parameters
icon- Icon object to convert.
attrs- (Optional) attributes to add to the element.
charm.replaceElement(element, icon, attrs = {}, replaceAttr = 'data-charm')
Replaces a HTMLElement with an icon.
Parameters
element- The
HTMLElementto replace.
- The
icon- Icon to be transformed into a
HTMLElementand placed.
- Icon to be transformed into a
attrs- (Optional) attributes to add to the element.
replaceAttr- Element attribute to be ignored - this will be
replaceAttrwhen invoked bycharm.placeIcons().
- Element attribute to be ignored - this will be
getAttrs(icon, attrs = {})
Get the combined attributes of an icon and given attributes.
Parameters
icon- An icon object. (
{name, paths, keywords})
- An icon object. (
attrs- (Optional) additional attributes.
Notes
charmandcharm-<icon name>classes are added to all icons by default. Use these classes how you please.
Contributing
Contributions are warmly welcomed. If you are contributing icon designs, please read the icon design guidelines.
Issues
Please use the GitHub issue tracker to track issues.
Icon Requests
Please see the icon request issue template for submitting icon requests.
README Badge
Use this badge to let others know you're using Charm Icons!
[](https://github.com/jaynewey/charm-icons)