How I Fixed Next.js Serialization Errors in Payload CMS v3 by Building a Custom Icon Picker

Vachagan Achoyan — Thu, 04 Jun 2026 06:17:34 +0000

If you’ve recently migrated to Payload CMS v3, you’re probably loving the deep integration with Next.js and the App Router. However, moving to a full React Server Components (RSC) architecture brings a few unique engineering hurdles—especially when dealing with dynamic UI elements like icons.

Recently, while working on a project, I hit a frustrating roadblock with Next.js serialization limits and ended up building an open-source plugin to solve it properly.

Here is the story behind payload-icon-picker.

The Problem: The Dreaded Serialization Error ❌

I wanted to allow users to select and render custom icons directly within the Payload admin panel. My first instinct was to pass down dynamic icon components or raw SVG chunks.

But as soon as you try to pass heavy icon objects or binary data from a Server Component down to a Client Component prop, Next.js throws the infamous:

Error: Only plain objects can be passed to Client Components from Server Components. Objects with toJSON methods are not supported.

Using quick hacks like JSON.parse(JSON.stringify(data)) might unblock your custom frontend queries, but it completely breaks down when you inject custom fields into Payload's core admin panel layout.

The Solution: Designing a Safe Fallback Chain 🛠️

To solve this natively, I built payload-icon-picker. The main architecture principle is simple: Never pass un-serializable components through the wire.

Instead, the plugin captures the selected icon and saves it into the database as a clean, basic JSON object containing only the name and pre-rendered static SVG markup:

{
  "name": "lucide-icon-name",
  "svg": "<svg>...</svg>"
}

This data shape is completely safe for Next.js RSC boundary crossings and loads instantly everywhere.

High-Performance UI with TanStack Virtual

One of the biggest traps when building an icon picker is loading performance. If you import a massive pack like Lucide or Phosphor Icons all at once, rendering thousands of DOM nodes inside a select dropdown or modal will completely lag the browser.

To guarantee a premium, production-ready feel, I integrated @tanstack/react-virtual to handle virtualized grid rendering. Whether the user opens a dropdown or shifts to a sliding layout, the DOM only mounts the elements currently visible on the screen. It can render 2,000+ icons at a locked 60fps.

Context Awareness: Global vs Collection-Specific Packs

I took the plugin a step further by introducing context tracking via Payload's @payloadcms/ui.

Now, the field dynamically tracks which collection it's currently rendering in. This allows you to configure a global fallback pack (e.g., Lucide) but strictly inject isolated icon sets into specific collections (e.g., using Phosphor Icons only for your Categories collection).

Check It Out! 🚀

The plugin is fully production-ready, open-source, and available on npm right now https://www.npmjs.com/package/payload-icon-picker.

If you are building with Payload 3 and want an easy, native way to add highly optimized icon pickers without dealing with Next.js serialization bugs, feel free to grab it:

🔗 GitHub Repository: https://github.com/Metax7/payload-icon-picker