payload-icons

@pro-laico/payload-icons makes it as easy to create a completely custom icon set as using an off-the-shelf one like Lucide. Making asset sources like The Noun Project's a much easier tool to utilize, and giving designers and clients the freedom to edit SVG's from Payload admin, without breaking anything and maintaining optimizations.

You upload an .svg in the admin; the plugin optimizes, sanitizes, and themes it on save, then a single <Icon name="…" /> server component drops it into any page as a real, inline <svg> that recolors from CSS. No sprite sheet, no wrapper file, no untrusted markup reaching the browser.

pnpm add @pro-laico/payload-icons

What's included

A fully custom icon set, as easy to use as an off-the-shelf one:

• Add icons in the admin: upload an .svg and the plugin optimizes, sanitizes, and themes it on save — designers and clients can extend the set without touching code or breaking anything.
• One drop-in component: <Icon name="arrow-right" /> inlines a real, recolorable <svg> — as easy as Lucide, but it's your set.
• Swappable icon sets: a set maps lookup names to icons and one set is active, so activating a different set re-skins every icon at once (a seasonal pack, a heavier redraw, an A/B test).
• Never ship a missing icon: the Requested icons panel scans your code and tracks runtime misses, surfacing exactly which icons you still need.
• Declarative seeding: icons seed natively through @pro-laico/payload-seed — no helper, no provider.

Icon set Default, rendered in the /dev/icons route

Icon set Alternate, rendered in the /dev/icons route

Quickstart

import { buildConfig } from 'payload'
import { iconsPlugin } from '@pro-laico/payload-icons'

export default buildConfig({
  plugins: [iconsPlugin()],
})

pnpm payload generate:importmap

import { Icon } from '@pro-laico/payload-icons/components/Icon'

// resolves `arrow-right` through the active set and inlines a real <svg>
<Icon name="arrow-right" className="size-6 text-primary" />

Plugin options

iconsPlugin(options?) is the single entry point. One call registers the icon collection (upload pipeline, on-save optimizer), the iconSet grouping collection, and the iconRequest diagnostics collection. It's zero-config: the usage panel and request tracking are on by default; set them false to omit.

Pass options to customize. The Reference tab is the interactive view; TypeScript is the same shape in code, every defaulted option written out.

import { iconsPlugin } from '@pro-laico/payload-icons'

// Defaulted options written out. This is what `iconsPlugin()` does with no args.
iconsPlugin({
  enabled: true,
  includeIconSet: true,
  usagePanel: true,     // the "Requested icons" panel; set false to omit
  trackRequests: true,  // runtime miss tracking; set false to omit
  // overrides for the icon upload collection (slug / adminGroup / access / fields / hooks / upload):
  iconOverrides: {
    // slug: 'icon',
    // access: { read: () => true },
    // fields: [ /* … */ ],
    // hooks: { /* … */ },
  },
  // overrides for the iconSet collection:
  iconSetOverrides: {
    // fields: [{ name: 'description', type: 'textarea' }],
    // iconRowFields: [{ name: 'aliases', type: 'text', hasMany: true }],
  },
})

<Icon>

The frontend surface: one import, no wrapper file. The <Icon> server component resolves name through the active set and inlines the matched icon as a real <svg>: your className/props win over the SVG's intrinsic attributes, and it inherits CSS color via currentColor. Import from the components/Icon subpath:

import { Icon } from '@pro-laico/payload-icons/components/Icon'

<Icon name="arrow-right" className="size-6 text-primary" />

Props

import { Icon } from '@pro-laico/payload-icons/components/Icon'

// `name` is the only required prop; it resolves through the active set.
<Icon
  name="arrow-right"
  className="size-6 text-primary"
  // fallback={myCustomSvgString}  // shown if the name isn't in the active set
/>

Rendering it yourself

<Icon> is just getIconSvg (from the cache subpath, server-only and memoized per request) composed with the pure extractSvg* helpers. Call getIconSvg(name, draft) yourself to render an icon in your own markup (memoized, so a page calling it many times is still one query):

import { getIconSvg } from '@pro-laico/payload-icons/cache'
import { extractSvgContent, extractSvgProps } from '@pro-laico/payload-icons'

const svg = await getIconSvg('arrow-right') // draft defaults to false (published)
if (!svg) return null

return (
  <svg
    {...extractSvgProps(svg)}
    className="size-6"
    dangerouslySetInnerHTML={{ __html: extractSvgContent(svg) }}
  />
)

It reads the active set's _status: 'published' rows on the published frontend (and the latest draft in draft mode), so you never render an unpublished set.

Styling with CVA + Tailwind

Because the optimizer rewrites fills to currentColor and <Icon> forwards className straight onto the <svg>, one source SVG recolors and resizes from class names alone, with no custom wrapper needed. Pair <Icon> with class-variance-authority to turn size / tone props into classes, one variant per line so the axes stay legible:

import { cva } from 'class-variance-authority'

const iconClass = cva('inline-block shrink-0', {
  variants: {
    size: {
      xs: 'size-3.5',
      sm: 'size-4',
      base: 'size-5',
      lg: 'size-6',
      xl: 'size-8',
    },
    tone: {
      current: '',
      muted: 'text-muted-foreground',
      primary: 'text-primary',
      destructive: 'text-destructive',
    },
  },
  defaultVariants: { size: 'base', tone: 'current' },
})

import { Icon } from '@pro-laico/payload-icons/components/Icon'

// One source SVG, every variant; the cva className recolors and resizes it.
<Icon name="star" className={iconClass({ size: 'sm' })} />
<Icon name="star" className={iconClass({ size: 'lg', tone: 'primary' })} />
<Icon name="star" className={iconClass({ size: 'xl', tone: 'destructive' })} />

The icons-sandbox example ships the full version: a presentational Icon (CVA over the inline <svg>) plus a name-based CmsIcon server wrapper, along with a showcase page that renders one source SVG across the variant, size, and tone axes.

Collections

The plugin registers the icon upload collection (an Assets group), the iconSet grouping collection (a Sets group), and a hidden iconRequest diagnostics collection (on by default; disable with trackRequests: false). Icons accept SVG only, and every upload is sanitized before storage, so a .svg is safe to inline straight onto a page.

icon

The upload collection you add icons to. Each file is optimized and sanitized on save by the formatSVGHook beforeChange hook and stored inline as svgString. Read is public (icons are frontend assets); writes are logged-in-admin only. The admin titles each doc by filename.

Fields

Hooks

On save, formatSVGHook runs svgo (loaded dynamically, so it never lands in a frontend or edge bundle) and:

• Sanitizes untrusted SVGs: strips <script> elements, on* handlers, and javascript: URLs. The stored string is later inlined via dangerouslySetInnerHTML, so this runs even when geometry optimization is skipped.
• Optimizes with svgo (preset-default + path/number cleanup, dimensions removed).
• Themes by rewriting hard-coded fill/stroke to currentColor, so an icon takes its color from CSS.
• Normalizes the viewBox: tightened to the real path bounds and squared around the glyph's center, so mismatched source artboards render consistently.

iconSet

A named, ordered name → icon mapping into the shared icon pool, with a single-active toggle. Build a second set (a different arrow-right, a heavier weight, a seasonal pack) and flip it active to re-skin every icon at once, without touching the frontend. Writes and reads are logged-in-admin only; drafts / versions are on by default (toggle with drafts). Lives under a Sets admin group.

• Settings tab: the active toggle and title (plus any fields you add, and the usage panel unless usagePanel: false).
• Icons tab: the iconsArray, one row per icon, each a name (auto kebab-cased, what the frontend looks up, independent of the uploaded filename) and an icon upload relationship into the icon collection.

iconRequest

On by default (disable with trackRequests: false). A hidden diagnostics collection: every icon name that fails to resolve at runtime is recorded (throttled, fire-and-forget) with a hit count and first/lastRequestedAt timestamps. It's the runtime counterpart to the static scan, capturing dynamic names a static pass can't see. Surfaced in the IconSet usage panel, not browsed directly.

Icon Use Detection

Problem: code asks for a name the active set lacks → the fallback warning glyph, and it's easy to miss which icons a project actually needs.

Fix: the admin Requested icons panel (on by default) lists missing vs present names, from two sources:

• Static scan: greps your source for literal <Icon name="…">, flagging missing names with file:line. In dev the panel scans live, so there's nothing to set up or run. For production (source isn't on disk at runtime) run payload-icons-scan in your build to write an icon-usage-manifest.json the panel reads there.
• Runtime: on by default too, <Icon> logs names that fail to resolve at runtime (incl. dynamic name={slug} the scan can't see) into the hidden iconRequest collection, with hit counts, last-seen, and a clear button.

Both are on with iconsPlugin(); pass usagePanel: false / trackRequests: false to omit either.

payload-icons-scan            # production/CI: scans ./src and ./app; -o sets the manifest path

How it works

The active set, the read path, and revalidation fit together like this.

Resolving an icon

<Icon name="arrow-right" /> looks the name up in the active, published iconSet, finds the icon doc it points at, and inlines that doc's stored svgString as a real <svg> — recolorable through currentColor and sized by your own classes. The lookup reads through payload.find, memoized per request, so repeating the same icon on a page costs one query. The name is the set entry's name, not the uploaded filename, which is why swapping the active set re-skins every icon at once. A name the active set doesn't cover renders the fallback warning glyph and is recorded for the Requested icons panel.

Revalidation

The plugin does none. <Icon> reads via payload.find (memoized per request), so a statically rendered page bakes the SVG at build time and won't reflect an edit (or an active-set swap) until the route revalidates. Wire that yourself with afterChange / afterDelete hooks (e.g. calling revalidatePath) through the collections' hooks option.

Seeding

Because icon is a standard upload collection, it seeds natively — no script, and (unlike payload-mux) no custom.seedAsset marker. Seed it like any other collection with defineSeed: each record carries its source SVG on the _file meta-key via the file() token. Drop your source .svg files in the collection's folder under the seed assets dir (named after the slug, so assets/icon/star.svg resolves from file('star.svg')):

// src/seed/icons.ts — each icon doc carries its SVG on `_file`
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('icon', ({ file }) => [
  {
    _key: 'star',
    _file: file('star.svg'), // assets/icon/star.svg
  },
  {
    _key: 'check',
    _file: file('check.svg'), // assets/icon/check.svg
  },
])

Each doc is optimized on upload via the same formatSVGHook. An uploaded icon doesn't render on its own, though — the frontend resolves <Icon name> through the active set, so seed an iconSet that maps lookup names to those icons with ordinary ref('icon', …) tokens:

// src/seed/iconSets.ts — an active, published set wiring names to the seeded icons
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('iconSet', ({ ref }) => [
  {
    _key: 'default',
    title: 'Default',
    active: true,         // the live set
    _status: 'published', // visible to the non-draft frontend
    iconsArray: [
      { name: 'star', icon: ref('icon', 'star') },
      { name: 'check', icon: ref('icon', 'check') },
    ],
  },
])

Icons are equally referenceable from any other doc — e.g. a page's icon relationship:

// src/seed/pages.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('pages', ({ ref }) => [
  {
    _key: 'home',
    title: 'Home',
    icon: ref('icon', 'star'),
  },
])

Wire the definitions into the seed plugin as usual — icons precede the set and page that reference them:

import { iconsPlugin } from '@pro-laico/payload-icons'
import { seedPlugin } from '@pro-laico/payload-seed'
import icons from './seed/icons'
import iconSets from './seed/iconSets'
import pages from './seed/pages'

plugins: [iconsPlugin(), seedPlugin({ definitions: [icons, iconSets, pages] })]

Because icon is a real collection, its seed records are type-checked and other docs reference them with ref() — this package never imports the seed package, so the two stay decoupled. active: true makes the set live and _status: 'published' makes it visible to the published frontend; see the examples/icons-sandbox app for a full working setup, or the seed plugin docs for the full reference.

Gotchas

A few things to keep in mind:

• Uploading an icon doesn't render it. <Icon name> resolves through the active, published set. Seeing the fallback glyph? Check, in order: a set is active, it's published (not just a draft), and the row name matches the name you pass (both are kebab-cased).
• The lookup name is the set entry's name, not the filename. Renaming an uploaded file changes nothing; the iconsArray row's name is the key your code references.
• Use fill-based SVGs, not stroke-based. The optimizer themes filled glyphs by rewriting their colors to currentColor. A stroke-drawn icon (Lucide/Feather-style fill="none" stroke="…") comes out with its enclosed shapes filled solid — a circle outline becomes a disk. Source solid-fill glyphs (Noun Project-style filled paths work; stroke sets don't). The upload detects the stroke signature and flags it in the doc's optimized report.
• <Icon> is an async server component. It queries Payload, so it can't render inside a client component — render it in a server component and pass the output down, or resolve the SVG yourself with getIconSvg.
• No revalidation built in. A statically rendered page bakes the SVG at build time and won't reflect an edit or an active-set swap until the route revalidates — wire revalidatePath / revalidateTag yourself through the collections' hooks.
• The static scan sees literal names only. A dynamic name={expr} is invisible to it (that's trackRequests' job at runtime), and in production the usage panel needs the payload-icons-scan manifest written during your build.

Exports