# Charm Icons [![CI](https://github.com/jaynewey/charm-icons/workflows/CI/badge.svg)](https://github.com/jaynewey/charm-icons/actions) [![GitHub](https://img.shields.io/github/license/jaynewey/charm-icons)](https://github.com/jaynewey/charm-icons/blob/main/LICENSE) [![npm](https://img.shields.io/npm/v/charm-icons)](https://www.npmjs.com/package/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](https://codepen.io/jaynewey/full/LYROoGJ) or have a quick look below:
You can also look at the icons on [icones](https://icones.js.org/collection/charm). ## Contents * [Inspiration / Motivation](#inspiration--motivation) * [Installation](#installation) - [NPM (Recommended)](#npm-recommended) - [CDN](#cdn) * [Usage](#usage) - [With ESModules (Recommended)](#with-esmodules-recommended) - [With CDN](#with-cdn) - [Using custom icons with the API](#using-custom-icons-with-the-api) - [API reference](#api-reference) - [Notes](#notes) * [Contributing](#contributing) * [Issues](#issues) - [Icon Requests](#icon-requests) ## Inspiration / Motivation `charm-icons` takes inspiration from the following icon sets but tries to differ in key aspects. * [Octicons](https://github.com/primer/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](https://github.com/lucide-icons/lucide) - 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: ```bash 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 ```html ``` #### Minified ```html ``` ### Iconify `charm` is available via [iconify](https://github.com/iconify/iconify). Iconify has component libraries for React, Vue, Svelte and Ember. ## Usage You may use the SVG files ([found here](/icons)) 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: ```html ``` Your javascript will look like one of the following: #### Treeshaking (Recommended) ```javascript // 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 ```javascript // This will still bundle any unused icons. import { placeIcons, icons } from 'charm-icons'; placeIcons({ icons: icons }); ``` ### With CDN ```html ``` ### Using custom icons with the API _See [this codepen demo](https://codepen.io/jaynewey/pen/wvovOQX) 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: ```html
``` ```js const Test = { name: 'test', paths: '', keywords: ['beaker', 'development', 'experimental', 'lab', 'science', 'study'], }; ``` You can then pass the new icon to `placeIcons()`: ```js 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-` 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](https://github.com/jaynewey/charm-icons/tree/main/docs/ICON_GUIDELINES.md). ## Issues Please use the [GitHub issue tracker](https://github.com/jaynewey/charm-icons/issues) to track issues. ### Icon Requests Please see the [icon request issue template](https://github.com/jaynewey/charm-icons/tree/main/.github/ISSUE_TEMPLATE) for submitting icon requests. ## README Badge Use this badge to let others know you're using 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) ``` [![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) ```