Lucide Icon Picker for Strapi

A Strapi v5 custom field plugin that provides an intuitive icon picker for Lucide icons. Icons are stored as kebab-case strings and accessible via the Strapi API.

⚠️ Upgrading from lucide-react 0.x

Starting with 2.0.0, this plugin uses lucide-react ^1.x. Lucide 1.0 renamed several icons (e.g. check-circle → circle-check, x-circle → circle-x) and removed all brand icons (GitHub, Slack, Figma, etc.) entirely — see Lucide's upgrade guide for the full list. If your existing content uses one of those names, it will silently fall back to a placeholder icon after upgrading, since that icon no longer exists.

If you have existing content and aren't ready to deal with that yet, stay on the last release built on lucide-react 0.x:

npm install @samuel-erb/strapi-plugin-lucide-icon-picker@^1.3.0

✨ Features

• 🎨 Visual Icon Browser - Browse through 1600+ Lucide icons with live preview
• 📂 Category Organization - Icons grouped by categories (Design, Text, Communication, etc.)
• 🔍 Smart Search - Filter icons by name, tags, and categories
• 🌙 Dark Mode Support - Seamless integration with Strapi's dark theme
• 💾 String Storage - Icons stored as kebab-case strings (e.g., "arrow-down")
• 🌐 API Ready - Access icon names through Strapi's REST & GraphQL APIs
• ✅ TypeScript Support - Full type safety and IntelliSense
• 📱 Responsive Design - Works seamlessly across all device sizes
• ⚡ Auto-sync - Automatically downloads latest icons from Lucide before building
• 🎯 Enhanced UX - Tooltips and improved visual feedback

🚀 Installation

1. Install the plugin in your Strapi project:

npm install lucide-icon-picker

2. Enable the plugin in config/plugins.js:

module.exports = () => ({
  'lucide-icon-picker': {
    enabled: true,
  },
});

3. Rebuild and restart your Strapi application:

npm run build
npm run develop

📖 Usage

Adding Icon Fields

1. Navigate to Content-Type Builder
2. Select an existing content type or create a new one
3. Click Add another field
4. Choose Custom → Lucide Icon
5. Configure your field settings and save

Content Management

The icon picker provides an intuitive interface where you can:

• Browse icons in a grid layout
• Search by icon name
• Preview icons in real-time
• Clear selections easily

Frontend Integration

API Response Format

Icons are returned as kebab-case strings in your API responses:

{
  "data": {
    "id": 1,
    "attributes": {
      "title": "My Article",
      "icon": "arrow-down",
      "publishedAt": "2024-01-15T10:00:00.000Z"
    }
  }
}

Rendering an icon name from Strapi in React

Wrap the kebab-case strings in one component that does validation, lazy-loading and a fallback.

// components/ApiIcon.tsx
import { DynamicIcon, dynamicIconImports } from "lucide-react/dynamic";
import type { LucideProps } from "lucide-react";

// Same set of names lucide-react actually ships — used to validate Strapi input.
type IconName = keyof typeof dynamicIconImports;

function isValidIconName(name: string): name is IconName {
  return name in dynamicIconImports;
}

interface ApiIconProps extends LucideProps {
  name: string; // raw, unvalidated string as it comes from Strapi
}

export default function LucideIcon({ name, ...props }: ApiIconProps) {
  // Guard against renamed/removed/typo'd icon names from Strapi so a bad
  // value can't crash rendering — fall back to a neutral placeholder icon.
  if (!isValidIconName(name)) {
    return <DynamicIcon name="circle-help" {...props} />;
  }

  // DynamicIcon code-splits and lazy-loads only the icons actually used,
  // instead of bundling all ~1800 lucide icons.
  return <DynamicIcon name={name} {...props} />;
}

🎨 Available Icons

This plugin supports all icons from the Lucide icon library, including:

• Interface icons (arrows, buttons, controls)
• Communication icons (mail, phone, chat)
• Media icons (play, pause, volume)
• File and folder icons
• And many more...

🛠 Development

Requirements

• Node.js 20–24
• Strapi v5.x
• React 18+

Building the Plugin

# Install dependencies
npm install

# Download latest Lucide icons and build the plugin
npm run build

# Or update icons manually
npm run update:lucide-data

# Run TypeScript checks
npm run test:ts:front
npm run test:ts:back

# Watch for changes during development
npm run watch

Testing

The plugin can be tested locally using Yalc:

# In the plugin directory
npm run build
npx yalc publish

# In your Strapi project
npx yalc add lucide-icon-picker
npm install
npm run develop

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and enhancement requests.

☕ Support

If you find this plugin helpful, consider supporting its development:

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with the Strapi Plugin SDK
• Icons provided by Lucide
• Inspired by the Strapi community's needs for better icon management