@xtreat/solid-iconify
Version:
A reactive and first class native Solid Iconify icon component
182 lines (125 loc) • 6.15 kB
Markdown
# @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 (
<>
<Icon icon="mdi:account" width={32} height={32} />
<Icon icon="fa:user" color="tomato" />
</>
);
}
export default App;
```
#### With Custom Configuration
```tsx
import { configureIconify } from "@xtreat/solid-iconify";
configureIconify({
ICONIFY_API: ["api.iconify.design", "yourapihere.com"],
SANITIZE: true,
});
```
## 🧩 API
### `<Icon />` 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<string | URL>,
REQUEST_OPTIONS: RequestInit,
CACHE_SIZE: number | { strategy: "grow" | "static" | "unlimited" },
COLLECTION_SIZE: number | { strategy: "grow" | "static" | "unlimited" },
DEFAULT_SVG_ATTRIBUTES: Partial<JSX.SvgSVGAttributes<SVGSVGElement>>,
SANITIZE: boolean,
SANITIZE_OPTIONS: Partial<IFilterXSSOptions>,
});
```
## 🏗️ 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";
<Icon icon="mdi:home" width={48} color="#0078d4" />
```
## 💬 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