svelvg

Convert SVG files into Svelte components with TypeScript definitions.

Successor to svg-to-svelte

The minimum Svelte version required to use types generated by this library is v3.55.0.

This library transforms SVG files into Svelte components through the following:

• convert the svg file name into a valid module name (e.g., alarm-fill --> AlarmFill)
• forward $$restProps to the svg element while preserving attributes from the original svg
• add a default slot as child element to svg
• generate a TypeScript definition by extending the SvelteComponentTyped interface

Usage

CLI

The easiest way to use this library is through npx.

The glob value represents the relative path to the folder containing SVG files inside node_modules/.

For example, say you have bootstrap-icons installed as a development dependency, which contains icon SVG files in the "icons" folder.

npx svelvg glob=bootstrap-icons/icons

By default, the output directory is "lib". Customize the directory using the outDir flag:

npx svelvg glob=bootstrap-icons/icons outDir=dist

Optionally, generate an index of icons (a list of all module names) by enabling the iconIndex flag. It will default to creating a ICON_INDEX.md file in your working directory.

npx svelvg glob=bootstrap-icons/icons iconIndex

Customize the icon index file name like so:

npx svelvg glob=bootstrap-icons/icons iconIndex=ICONS.md

Programmatic usage

Alternatively, install svelvg from NPM to use it programmatically.

# NPM
npm i -D svelvg

# pnpm
pnpm i -D svelvg

# Bun
bun add -D svelvg

# Yarn
yarn add -D svelvg

import { createLibrary } from "svelvg";

// Generate Svelte components from SVG files in `node_modules/bootstrap-icons/icons`.
// By default, output is emitted to the `lib` directory.
createLibrary("bootstrap-icons/icons");

// Customize the output directory to `dist`.
createLibrary("bootstrap-icons/icons", { outDir: "dist" });

API

createLibrary

type CreateLibraryOptions = {
  /** @default "lib" */
  outDir: string;

  /** @default false */
  iconIndex: boolean | string;

  /**
   * Callback to add a list of classes to the SVG element
   * provided the original filename and module name
   * @example
   * filename: "alarm-fill"
   * moduleName: "AlarmFill"
   */
  appendClassNames: (filename: string, moduleName: string) => string[];

  /**
   * Override the default module name
   */
  toModuleName: (params: {
    path: path.ParsedPath;
    moduleName: string;
  }) => string;
};

Template

Scaffold a new project using the template:

npx degit metonym/svelvg/template <folder-name>

IconLibrary.svelte

svelvg exports an IconLibrary.svelte to make listing and searching icons easier.

See template/index.html for an example.

<script type="module">
  import IconLibrary from "svelvg/lib/IconLibrary.svelte";
  import * as icons from "./lib";
  import pkg from "./package.json";

  const app = new IconLibrary({
    target: document.getElementById("svelte"),
    props: {
      pkg,
      icons,
    },
  });
</script>

License

MIT