Icons

Import icons from the most popular icon libraries

Options See on deno.land

folder string
Default: 
"/icons"
catalogs object[]
Default: 
[
  {
    id: "bootstrap",
    src: "https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/icons/{name}.svg"
  },
  {
    id: "heroicons",
    src: "https://cdn.jsdelivr.net/npm/heroicons@2.2.0/{variant}/{name}.svg",
    variants: [
      { id: "outline", path: "24/outline" },
      { id: "solid", path: "24/solid" },
      { id: "minimal", path: "20/solid" },
      { id: "micro", path: "16/solid" }
    ]
  },
  {
    id: "lucide",
    src: "https://cdn.jsdelivr.net/npm/lucide-static@0.468.0/icons/{name}.svg"
  },
  {
    id: "material-100",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-100@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-200",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-200@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-300",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-300@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-400",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-400@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-500",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-500@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-600",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-600@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material-700",
    src: "https://cdn.jsdelivr.net/npm/@material-symbols/svg-700@0.27.2/{variant}/{name}.svg",
    variants: [ "outlined", "rounded", "sharp" ]
  },
  {
    id: "material",
    src: "https://cdn.jsdelivr.net/npm/@material-design-icons/svg@0.14.13/{variant}/{name}.svg",
    variants: [ "filled", "outlined", "round", "sharp", "two-tone" ]
  },
  {
    id: "mingcute",
    src: "https://cdn.jsdelivr.net/gh/Richard9394/MingCute@2.95/svg/{name}.svg"
  },
  {
    id: "phosphor",
    src: "https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2.1.1/assets/{variant}/{name}.svg",
    name: [Function: name],
    variants: [ "regular", "bold", "duotone", "fill", "light", "thin" ]
  },
  {
    id: "remix",
    src: "https://cdn.jsdelivr.net/npm/remixicon@4.5.0/icons/{name}.svg",
    name: [Function: capitalize]
  },
  {
    id: "simpleicons",
    src: "https://cdn.jsdelivr.net/npm/simple-icons@13.20.0/icons/{name}.svg"
  },
  {
    id: "tabler",
    src: "https://cdn.jsdelivr.net/npm/@tabler/icons@3.24.0/icons/{variant}/{name}.svg",
    variants: [ "filled", "outline" ]
  },
  {
    id: "myna",
    src: "https://cdn.jsdelivr.net/npm/@mynaui/icons@0.3.3/{variant}/{name}.svg",
    variants: [
      { id: "regular", path: "icons" },
      { id: "solid", path: "icons-solid" }
    ]
  },
  {
    id: "iconoir",
    src: "https://cdn.jsdelivr.net/npm/iconoir@7.10.1/icons/{variant}/{name}.svg",
    variants: [ "regular", "solid" ]
  },
  {
    id: "sargam",
    name: [Function: capitalize],
    src: "https://cdn.jsdelivr.net/npm/sargam-icons@1.4.8/Icons/{variant}/si_{name}.svg",
    variants: [
      { id: "duotone", path: "Duotone" },
      { id: "fill", path: "Fill" },
      { id: "line", path: "Line" }
    ]
  },
  {
    id: "boxicons",
    src: "https://cdn.jsdelivr.net/npm/boxicons@2.1.4/svg/{variant}-{name}.svg",
    variants: [
      { id: "regular", path: "regular/bx" },
      { id: "solid", path: "solid/bxs" },
      { id: "logos", path: "logos/bxl" }
    ]
  },
  {
    id: "ant",
    src: "https://cdn.jsdelivr.net/npm/@ant-design/icons-svg@4.4.2/inline-namespaced-svg/{variant}/{name}.svg",
    variants: [ "filled", "outlined", "twotone" ]
  },
  {
    id: "fluent",
    src: "https://cdn.jsdelivr.net/npm/@fluentui/svg-icons@1.1.267/icons/{name}_{variant}.svg",
    variants: [
      { id: "outlined", path: "regular" },
      "filled",
      { id: "twotone", path: "color" }
    ]
  },
  {
    id: "octicons",
    src: "https://cdn.jsdelivr.net/npm/@primer/octicons@19.13.0/build/svg/{name}-{variant}.svg",
    variants: [ "24", "16", "12", "48", "96" ]
  },
  {
    id: "openmoji",
    src: "https://cdn.jsdelivr.net/npm/openmoji@15.0.0/{variant}/svg/{name}.svg",
    variants: [ "color", "black" ]
  }
]

Description

This plugin register the icon filter to download icons from the most popular icon libraries on demand.

Installation

Import this plugin in your _config.ts file to use it:

import lume from "lume/mod.ts";
import icons from "lume/plugins/icons.ts";

const site = lume();

site.use(icons(/* Options */));

export default site;

Usage

The icon filter downloads the SVG file of the icon and returns the path to this file so you can use it in your templates. For example to use the fire icon from Bootstrap library:

<img src="{{ "fire" |> icon("bootstrap") }}">

By default, the SVG files are downloaded to the /icons folder, creating a subfolder per collection. In the previous example, the icon would be saved to /icons/bootstrap/fire.svg. It's possible to configure a different folder with the folder option:

site.use(icons({
  folder: "/img/icons",
}));

Variants

Some icons have different variations. For example, Phosphor has 6 different variations per icon. You can specify the variation with the name:variation syntax:

<img src="{{ "acorn:duotone" |> icon("phosphor") }}">

The icon file is saved to /icons/phosphor/acorn-duotone.svg (the variation is appended to the name).

Alternatively, you can set the variation in the second argument of the filter:

<img src="{{ "acorn" |> icon("phosphor", "duotone") }}">

This is useful if you want more control of the variant to use, and don't want to delegate this decision to the person responsible to edit the content.

Inline icons

To inline the icons in the HTML, you can combine this plugin with the inline plugin:

<img src="{{ "acorn" |> icon("phosphor") }}" inline>

Available libraries

This is a list of all available libraries suported out of the box by the plugin:

LibraryId(s)
Antant
Bootstrapbootstrap
Boxiconsboxicons
Fluentfluent
Heroiconsheroicons
Iconoiriconoir
Lucidelucide
Material Iconsmaterial
Material Symbolsmaterial-100, material-200, material-300, material-400, material-500, material-600, material-700
Mingcutemingcute
Mynamyna
Octiconsocticons
Openmojiopenmoji
Phosphorphosphor
Remix iconsremix
Sargamsargam
Simpleiconssimpleicons
Tablertabler

Use custom libraries

The catalogs option allows configure custom icons catalogs. Each catalog is an object with the following properties:

id (required)
The catalog Id used in the filter
src (required)
The URL pattern used to download the SVG icon from a CDN. JsDelivr is highly recommended but you can use any domain. The pattern should contain the {name} and {variant} placeholders that are replaced with the name and variant to build the final URL.
variants
If the catalog has different variants, they must be listed in this array. The variants can be a string or an object with the id and path properties. The first element of the array is considered the default variant.
name
If the path of the icon file does not correspond with the icon name, you can configure a function to return the final path.

Example

site.use(icons({
  catalog: [
    {
      id: "my-library",
      src: "https://my-cdn.com/icons/{name}-{variant}.svg",
      variants: [
        "filled",
        "outlined",
      ],
    },
  ],
}));

To use this library:

<img src="{{ iconName |> icon("my-library", "filled") }}">