https://github.com/xandertreat/solid-iconify
A light-weight and performant native Solid.js first class Iconify component with configuration and type-safety
https://github.com/xandertreat/solid-iconify
component esm icon iconify js jsx npm solidjs svg ts tsx vector
Last synced: about 2 months ago
JSON representation
A light-weight and performant native Solid.js first class Iconify component with configuration and type-safety
- Host: GitHub
- URL: https://github.com/xandertreat/solid-iconify
- Owner: xandertreat
- License: mit
- Created: 2025-06-05T06:19:36.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-09T18:01:41.000Z (about 1 year ago)
- Last Synced: 2025-10-03T18:57:54.913Z (9 months ago)
- Topics: component, esm, icon, iconify, js, jsx, npm, solidjs, svg, ts, tsx, vector
- Language: TypeScript
- Homepage: https://github.com/xandertreat/solid-iconify
- Size: 130 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @xtreat/solid-iconify
[](https://www.npmjs.com/package/@xtreat/solid-iconify)
[](https://www.npmjs.com/package/@xtreat/solid-iconify)
[](https://bundlephobia.com/package/@xtreat/solid-iconify)
[](https://www.npmjs.com/package/@xtreat/solid-iconify)
[](https://github.com/xandertreat/textual-theme-gen/actions)
[](https://img.shields.io/badge/maintained-yes-brightgreen)
[](https://github.com/xandertreat/textual-theme-gen/issues)
[](https://github.com/xandertreat/textual-theme-gen/pulls)
[](https://github.com/xandertreat/textual-theme-gen/blob/main/LICENSE)
[](https://biomejs.dev/)
[](https://www.solidjs.com/)
[](https://github.com/xandertreat/textual-theme-gen/fork)
[](https://github.com/xandertreat/textual-theme-gen)
[](https://visitor-badge.laobi.icu/badge?page_id=xandertreat.textual-theme-gen)
A blazing-fast, fully reactive, and type-safe [SolidJS](https://www.solidjs.com/) component for rendering [Iconify](https://iconify.design/) icons. Designed for both SSR and client-side rendering, with first-class TypeScript support, flexible configuration, and zero runtime dependencies (besides SolidJS).
---
## ✨ Features
- **Reactive**: Icons update automatically when props change.
- **Type-Safe**: Full TypeScript support, including strict icon specifier validation.
- **SSR-Ready**: Works seamlessly with SolidJS server-side rendering.
- **Configurable**: Customize API endpoints, caching, SVG defaults, and more.
- **Flexible**: Supports all Iconify icon sets and custom collections.
- **Lightweight**: Minimal runtime, no unnecessary dependencies.
- **Secure**: Optional sanitization with [xss](https://www.npmjs.com/package/xss).
- **Modern**: ESM-only, ships with `.jsx` and TypeScript types
---
## 🚀 Quick Start
### 1. Install
```sh
npm install @xtreat/solid-iconify
# or
yarn add @xtreat/solid-iconify
# or
bun add @xtreat/solid-iconify
```
### 2. Usage
```tsx
import Icon from "@xtreat/solid-iconify";
function App() {
return (
<>
>
);
}
export default App;
```
#### With Custom Configuration
```tsx
import { configureIconify } from "@xtreat/solid-iconify";
configureIconify({
ICONIFY_API: ["api.iconify.design", "yourapihere.com"],
SANITIZE: true,
});
```
---
## 🧩 API
### `` Props
| Prop | Type | Description |
|--------------|-------------------------|-----------------------------------|
| `icon` | `string` (e.g. `mdi:account`) | **Required.** Iconify icon specifier |
| ...SVG props | | Any valid SVG attribute |
### `configureIconify(config)`
Configure global defaults for all icons. Accepts a partial config object:
```ts
configureIconify({
ICONIFY_API: string | URL | Array,
REQUEST_OPTIONS: RequestInit,
CACHE_SIZE: number | { strategy: "grow" | "static" | "unlimited" },
COLLECTION_SIZE: number | { strategy: "grow" | "static" | "unlimited" },
DEFAULT_SVG_ATTRIBUTES: Partial>,
SANITIZE: boolean,
SANITIZE_OPTIONS: Partial,
});
```
---
## 🏗️ How It Works
- **Reactive Fetching:** Uses Solid's `createResource` to fetch and cache SVGs from the Iconify API.
- **Caching:** LRU cache for icons and collections, configurable for memory efficiency.
- **Sanitization:** Optionally sanitizes SVGs for XSS protection.
- **SSR Support:** Works in both server and client environments.
---
## 🧪 Testing
This package uses [Vitest](https://vitest.dev/) for unit and e2e tests. To run tests:
```sh
npm test
```
---
## 📦 Build & Publish
- Build: `npm run build`
- Lint: `npm run lint`
- Format: `npm run format`
- Type-check: `npm run check`
---
## 🛡️ TypeScript Types
All types are exported:
```ts
import type {
IconifyIconProps,
IconifyConfig,
// ...etc
} from "@xtreat/solid-iconify";
```
---
## 📚 Example
```tsx
import Icon from "@xtreat/solid-iconify";
```
---
## 💬 Feedback & Contributions
Issues and PRs are welcome! [Open an issue](https://github.com/xandertreat/solid-iconify/issues) or [submit a pull request](https://github.com/xandertreat/solid-iconify/pulls).
---
## 🔗 Links
- [Iconify Icon Explorer](https://icon-sets.iconify.design/)
- [SolidJS Docs](https://www.solidjs.com/docs)
- [Project Repository](https://github.com/xandertreat/solid-iconify)
---
## 🐞 Known Bugs
- **Icon reactivity broken**: Changing the `icon` prop does not always update the rendered SVG as expected.
---
## 📝 License
MIT © 2025 Xander Treat