icon-pingu
v1.0.0
Published
A semantic, AI-assisted icon library for web development with intelligent icon resolution
Maintainers
lingupinguReadme
icon-pingu 🐧
A semantic, AI-assisted icon library for web development with intelligent icon resolution. Stop searching through icon catalogs - just describe what you need!
Features
- Semantic Icon Resolution: Describe icons in natural language
- 70+ Curated Icons: Based on the popular Lucide icon set
- AI-Ready: Placeholder for LLM integration for fuzzy matching
- Framework Agnostic: Works with React, Vue, vanilla JS, and more
- Zero Dependencies: Lightweight and production-ready
- TypeScript Friendly: Works great with TypeScript projects
Installation
npm install icon-pinguQuick Start
Basic Usage
const { getIcon } = require('icon-pingu');
// Get an icon by semantic description
const closeIcon = getIcon('close modal');
const searchIcon = getIcon('magnifying glass');
const cartIcon = getIcon('shopping');
console.log(closeIcon); // Returns SVG stringReact Usage
import { getIcon } from 'icon-pingu';
function MyComponent() {
const closeIcon = getIcon('close modal');
const saveIcon = getIcon('save file');
return (
<div>
<button>
<div dangerouslySetInnerHTML={{ __html: closeIcon }} />
Close
</button>
<button>
<div dangerouslySetInnerHTML={{ __html: saveIcon }} />
Save
</button>
</div>
);
}React Component Wrapper
For cleaner React integration, create a reusable component:
import { getIcon } from 'icon-pingu';
function Icon({ name, className, ...props }) {
const svg = getIcon(name);
return (
<span
className={className}
dangerouslySetInnerHTML={{ __html: svg }}
{...props}
/>
);
}
// Usage
function App() {
return (
<div>
<Icon name="close modal" className="icon" />
<Icon name="user profile" className="icon" />
<Icon name="shopping cart" className="icon" />
</div>
);
}Vue Usage
<template>
<div>
<span v-html="closeIcon"></span>
<span v-html="saveIcon"></span>
</div>
</template>
<script>
import { getIcon } from 'icon-pingu';
export default {
data() {
return {
closeIcon: getIcon('close modal'),
saveIcon: getIcon('save file')
};
}
};
</script>Vanilla JavaScript
<!DOCTYPE html>
<html>
<head>
<title>Icon Pingu Example</title>
</head>
<body>
<div id="icon-container"></div>
<script src="node_modules/icon-pingu/index.js"></script>
<script>
const { getIcon } = require('icon-pingu');
const container = document.getElementById('icon-container');
container.innerHTML = getIcon('home');
</script>
</body>
</html>API Reference
getIcon(description: string): string
Resolves a semantic description to an SVG string.
Parameters:
description(string): Semantic description of the icon (e.g., "close modal", "shopping cart", "user profile")
Returns:
- SVG string ready to be rendered
Example:
const svg = getIcon('close modal');
// Returns: <svg xmlns="http://www.w3.org/2000/svg"...></svg>resolveIcon(description: string): string
Returns the icon ID without the SVG content. Useful for debugging.
Example:
const iconId = resolveIcon('close modal'); // Returns: "x"getAllIcons(): Array<string>
Returns an array of all available icon IDs.
Example:
const icons = getAllIcons();
// Returns: ["x", "check", "menu", "search", ...]getIconsByCategory(category: string): Array<string>
Returns icons filtered by category.
Categories: interface, navigation, user, social, communication, media, files, security, ecommerce
Example:
const mediaIcons = getIconsByCategory('media');
// Returns: ["camera", "image", "video", "music", ...]enableAI(aiResolverFn: Function): void
Enable AI-assisted icon resolution for fuzzy matching.
Example:
const { enableAI } = require('icon-pingu');
// Using OpenAI
enableAI(async (description) => {
const response = await openai.chat.completions.create({
model: "gpt-4",
messages: [{
role: "system",
content: "You are an icon matcher. Return ONLY the icon ID that best matches the description."
}, {
role: "user",
content: description
}],
temperature: 0.3
});
return response.choices[0].message.content.trim();
});
// Now fuzzy descriptions will work better
const icon = getIcon("button to dismiss notification");Available Icons
icon-pingu includes 70+ carefully curated icons covering common use cases:
Interface: close (x), check, menu, search, settings, bell, info, alert-circle, alert-triangle, help-circle, eye, eye-off, plus, minus, filter, loader, maximize, minimize, refresh-cw, external-link, link, copy, clipboard
Navigation: home, chevron-right, chevron-left, chevron-up, chevron-down, arrow-right, arrow-left, arrow-up, arrow-down
User & Social: user, heart, star, share
Communication: mail, phone, message-circle
Media: camera, image, video, music, play, pause, stop-circle
Files: file, folder, edit, save, download, upload, trash
Security: lock, unlock
E-commerce: shopping-cart, credit-card
Other: calendar, clock, globe, map-pin, sun, moon, wifi, wifi-off, zap, trending-up, trending-down
Semantic Matching Examples
The library uses intelligent keyword matching to resolve descriptions:
| Description | Matches Icon | |------------|--------------| | "close modal" | x | | "delete item" | trash | | "shopping" | shopping-cart | | "location" | map-pin | | "hamburger menu" | menu | | "magnifying glass" | search | | "checkmark" | check | | "light mode" | sun | | "dark mode" | moon |
Customization
Styling Icons
All icons use currentColor for stroke, making them easy to style with CSS:
.icon {
width: 24px;
height: 24px;
color: #333;
}
.icon:hover {
color: #0066cc;
}
.icon-large {
width: 48px;
height: 48px;
}React with Inline Styles
<Icon
name="heart"
style={{
color: 'red',
width: '32px',
height: '32px'
}}
/>Icon Attribution
The icons in this library are sourced from Lucide, an open-source icon library.
Lucide License: MIT License
Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2022.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License
MIT License - See LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Adding New Icons
- Add the SVG file to the
/iconsfolder - Update
iconIndex.jsonwith semantic tags - Submit a pull request
Improving Semantic Matching
If you find descriptions that don't resolve correctly, please open an issue with:
- The description you used
- The icon you expected
- The icon you received (if any)
Roadmap
- [ ] Add more icons (100+ target)
- [ ] Built-in AI resolution with multiple LLM providers
- [ ] TypeScript definitions
- [ ] Icon preview CLI tool
- [ ] CDN hosting for direct browser usage
- [ ] React/Vue/Svelte dedicated packages
Support
If you find this package useful, please consider:
- Starring the repository
- Reporting issues
- Contributing new icons or improvements
Acknowledgments
- Icons provided by Lucide
- Inspired by the need for semantic icon search
- Built with ❤️ for the developer community
Made with 🐧 by icon-pingu