README

Heroicon Plus is a Statamic add-on that adds one icon field: the whole Heroicons library and your own SVG icons, side by side in one picker.

Features

Choose from the Heroicons library in four styles: outline, solid, mini and micro.
Search within a style.
Use your own SVG icons from the same picker. If the icon you want is not there, upload it from the picker and use it straight away. There is no need to leave the page.
Library icons take the color of the page they are on, or a color you choose when you choose the icon. So do your own icons, if they leave their colors open.

Versions

Add-on	Statamic	Vue
2.x	6	3
1.x	5	2

Stored values and icon addresses are the same in both, so moving from 1.x to 2.x changes no content. When you move, run the publish command below once with --force: 2.x's icon files take their color from the page, where 1.x's are always near-black.

How to install

composer require technical911/heroicon-plus
php artisan technical911-heroicon-plus:publish

The first command also puts the built picker in public/vendor/heroicon-plus (Statamic's install step does this on every Composer run, so a site needs no build of its own). The second publishes the icons to public/vendor/technical911-heroicon-plus. You only need it once, and not at all if you keep the published icons in git. Add --force to overwrite files already there.

Custom icons need Statamic's assets asset container at public/assets, which a new Statamic site has. They live in public/assets/icons.

How to use

Add a field of type Heroicon Plus to a blueprint or fieldset. In the control panel the field shows the current icon, with Choose… and Clear. Choose… opens the picker. Click an icon, choose a color for it if you want one, and click Use this icon.

The field stores style:name, for example solid:academic-cap or custom:my-logo. In a template it gives the icon's address:

<img src="{{ my_icon }}" alt="">

{{ svg :src="my_icon" :style="my_icon:style" class="w-10 h-10" }}

Give the svg tag no viewBox. Each style has its own drawing size (outline and solid 24, mini 20, micro 16), and one written in the tag replaces the file's, so mini and micro would draw small, in a corner.

Colors

Drawn with the svg tag, every library icon takes the color of the page it is on, so a class like text-emerald-200 colors it, with no choice to make.

To give one icon a color of its own, click it in the picker. A window shows it as it would look on a light page and on a dark one, with a color wheel next to it: click or drag on the wheel for the color and how pale it is, and use the bar under it for how dark. One-click colors sit under the bar, and the box takes a typed code. No color takes a color off. Use this icon stores the icon in the color showing, and Back returns to the icons with nothing changed. To change only the color, click the icon the field already has: the picker opens with it in view.

The field's settings hold the one-click colors (Swatches, as hex codes) and whether any other color may be chosen (Allow Any Color, which shows the wheel and the box). With no swatches and no other colors allowed there is nothing to ask, so clicking an icon chooses it at once, and a color the field already holds stays until it is cleared.

A chosen color is stored after the icon, for example outline:users:#f59e0b. In a template, :style="my_icon:style" puts it on the svg tag, as above, and {{ my_icon:color }} gives the code alone. With no color chosen the tag gets no style at all, and the field gives a plain string. With one, {{ my_icon }} still prints the address, but the field is an object with value, color and style wherever it is turned into JSON.

The attributes on the svg tag come before the file's own and win over them, so a tag's stroke-width sets the line of an outline icon, as it does on an uploaded icon with its line width on its <svg>. With none, an outline icon keeps Heroicons' usual 1.5. A filled icon ignores the tag's fill and stroke: it stays filled, with no outline.

An <img> cannot take a color: use the svg tag where the color matters. An uploaded SVG takes a color only if it leaves its colors open with currentColor; one that paints its own colors keeps them on the page.

Custom icons

Upload an icon is on the picker's own screen. It sends your SVG file (one ending in .svg) through Statamic's own upload, so Statamic's permission check and SVG cleaning apply, and the new icon opens in the same window, as if you had clicked it. If an icon of that name already exists, nothing is overwritten and the picker shows you the existing one.

To rename or delete a custom icon, use Manage in Assets on the Custom tab, which opens the folder on Statamic's Assets page in a new tab. Refresh reloads the list.

Upload an icon appears for whoever Statamic allows to upload to that asset container, and Manage in Assets for whoever may view it. A super user always gets both.

Developing the add-on

Composer first, because @statamic/cms comes from the add-on's own vendor folder:

composer install
npm install
npm run build

npm run build makes sure every library icon takes its color from the page (scripts/make-icons-inherit-color.js), regenerates the icon name lists in resources/icons/indexes from the icon folders, then builds the picker into resources/dist/build. Commit the result: that folder is what sites receive.

./vendor/bin/phpunit
npm test

License

MIT

technical911 / heroicon-plus

Package info

Security

Statistics