Skip to content

Latest commit

 

History

History
284 lines (189 loc) · 8.59 KB

README.md

File metadata and controls

284 lines (189 loc) · 8.59 KB
Raw

Charm Icons

CI GitHub npm

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-width property, unlike charm.
      • Thus, charm allows for more customisation, and the icons tend to be smaller in file size.
  • Lucide / Feather
    • Lucide Icons are primarily designed for 24x24 pixel resolution whereas charm aims to look best at 16x16 pixel resolution.
      • For this reason, charm may work quite well alongside Lucide (be wary of design differences!).

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-icons

CDN

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

  • attrs

    • Attributes to add to every icon replaced by placeIcon e.g { class: "my-class my-other-class"}

  • replaceAttr

    • placeIcons replaces all elements with the replaceAttr (by default 'data-charm') attribute with the icon specified, e.g data-charm="at-sign".
      • Note: here you use kebab-case for the icon name (at-sign instead of AtSign)

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 HTMLElement to replace.
  • icon
    • Icon to be transformed into a HTMLElement and placed.
  • attrs
    • (Optional) attributes to add to the element.
  • replaceAttr
    • Element attribute to be ignored - this will be replaceAttr when invoked by charm.placeIcons().

getAttrs(icon, attrs = {})

Get the combined attributes of an icon and given attributes.

Parameters
  • icon
    • An icon object. ({name, paths, keywords})
  • attrs
    • (Optional) additional attributes.

Notes

  • charm and charm-<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!

Charm Icons

[![Charm Icons](https://img.shields.io/badge/charm%20icons-%2350C878.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAAGXRFWHRTb2Z0d2FyZQB3d3cuaW5rc2NhcGUub3Jnm+48GgAAANpJREFUOI2tk7FNA0EQRd/i7ERC4oQ6aAC3cCJyJW4Dd+HQEj2ckYCEAkhw5ogAEj8H/BOLpUPA+Us/mfn7Z3ZmF04NdaY+qJ3ahl1is2N9OTpcgFdgB7wBV0ndA+fABXBZSnGo+tRPLNSJehdOElOdDrW99QsvalPlm8R6bNXr2uBJfU6VXrhSS7iqjBfRPtYGnbpJq0114DbsDZtoNmpXG7TqXl33w1SXVcvLDBh1HW0LcPbDRn+PU1xh9BDHrbES/vkhjX7K37aQxBz4SOgmBHgH5oP/4L84AFJ3wx0yZi/SAAAAAElFTkSuQmCC)](https://github.com/jaynewey/charm-icons)