/unplugin

A sprite sheet generator plugin for Phosphor Icons

Primary LanguageJavaScriptMIT LicenseMIT

Warning

This plugin is extremely experimental, and is subject to change. Use at your own risk!

@phosphor-icons/unplugin

An unplugin for transforming your Phosphor Icon imports into static SVG sprite sheets. Multiple frameworks, metaframeworks, and build tooling supported, although very much WIP. Explore all our icons at phosphoricons.com.

NPM Travis Travis

GitHub stars GitHub forks GitHub watchers Follow on GitHub

Installation

npm i -D @phosphor-icons/unplugin
#^ or whatever package manager you use
Vite
// vite.config.ts
import PhosphorUnplugin from "@phosphor-icons/unplugin/vite";

export default defineConfig({
  plugins: [
    PhosphorUnplugin({
      framework: "react",
      assetPath: "/assets/phosphor.svg"
    }),
  ],
});

Example: playground/react-vite


Rollup
// rollup.config.js
import PhosphorUnplugin from "@phosphor-icons/unplugin/vite";

export default {
  plugins: [
    PhosphorUnplugin({
      /* options */
    }),
  ],
};


Webpack
// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require("@phosphor-icons/unplugin/webpack")({
      /* options */
    }),
  ],
};


Nuxt
// nuxt.config.js
export default defineNuxtConfig({
  modules: [
    [
      "@phosphor-icons/unplugin/nuxt",
      {
        framework: "vue",
        /* options */
      },
    ],
  ],
});

This module works for both Nuxt 2 and Nuxt Vite


Vue CLI
// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require("@phosphor-icons/unplugin/webpack")({
        framework: "vue",
        /* options */
      }),
    ],
  },
};


esbuild
// esbuild.config.js
import { build } from "esbuild";
import PhosphorUnplugin from "@phosphor-icons/unplugin/esbuild";

build({
  plugins: [PhosphorUnplugin({ framework: "react" })],
});


Options

The plugin can be configured to work with

  • framework?: "react" | "svelte" | "vue" — The base framework of your code. Defaults to "react".
  • assetPath?: string — The relative URL at which the generated sprite sheet will be placed. Defaults to /phosphor.svg.
  • packageName?: string — Override the default Phosphor package which will be transformed. The default depends on th framework chosen:
    • react: @phosphor-icons/react
    • vue: @phosphor-icons/vue
    • svelte: phosphor-svelte

Usage

Import icons from the Phosphor package as normal, making sure that all props passed to rendered icons are literal values:

// App.tsx
import { Smiley, SmileySad } from "@phosphor-icons/react";

function App() {
  return (
    <p>
      <span>Hello, world! Yesterday I was</span>
      <SmileySad color="blue" size="2em" />
      <span>, today I am</span>
      <Smiley weight="fill" color="goldenrod" size="3em" />
      <span>!</span>
    </p>
  );
}

This will be transformed at build-time into something resembling this:

// App.tsx
import { Smiley, SmileySad } from "@phosphor-icons/react";

function App() {
  return (
    <p>
      <span>Hello, world! Yesterday I was</span>
      <svg color="blue" width="2em" height="2em">
        <use href="/phosphor.svhgsmiley-sad-regular" />
      </svg>
      <span>, today I am</span>
      <svg color="goldenrod" width="3em" height="3em">
        <use href="/phosphor.svg#smiley-fill" />
      </svg>
      <span>!</span>
    </p>
  );
}

And a sprite sheet will be generated and placed at assetPath in the public directory of your build directory:

<!-- phosphor.svg -->
<svg xmlns="http://www.w3.org/2000/svg">
  <symbol viewBox="0 0 256 256" fill="currentColor" id="smiley-sad-regular">
    <path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm0,192a88,88,0,1,1,88-88A88.1,88.1,0,0,1,128,216ZM80,108a12,12,0,1,1,12,12A12,12,0,0,1,80,108Zm96,0a12,12,0,1,1-12-12A12,12,0,0,1,176,108Zm-1.08,64a8,8,0,1,1-13.84,8c-7.47-12.91-19.21-20-33.08-20s-25.61,7.1-33.08,20a8,8,0,1,1-13.84-8c10.29-17.79,27.39-28,46.92-28S164.63,154.2,174.92,172Z"></path>
  </symbol>
  <symbol viewBox="0 0 256 256" fill="currentColor" id="smiley-fill">
    <path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24ZM92,96a12,12,0,1,1-12,12A12,12,0,0,1,92,96Zm82.92,60c-10.29,17.79-27.39,28-46.92,28s-36.63-10.2-46.92-28a8,8,0,1,1,13.84-8c7.47,12.91,19.21,20,33.08,20s25.61-7.1,33.08-20a8,8,0,1,1,13.84,8ZM164,120a12,12,0,1,1,12-12A12,12,0,0,1,164,120Z"></path>
  </symbol>
</svg>

In future, we hope to support dynamic and computed props for all frameworks and build tooling, but at the moment any non-literal props will cause the build process to fail.

Our Related Projects

Community Projects

If you've made a port of Phosphor and you want to see it here, just open a PR here!

License

MIT © Phosphor Icons