@xtreat/solid-iconify

A blazing-fast, fully reactive, and type-safe SolidJS component for rendering Iconify 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.
• Modern: ESM-only, ships with .jsx and TypeScript types

---

🚀 Quick Start

1. Install

npm install @xtreat/solid-iconify
# or
yarn add @xtreat/solid-iconify
# or
bun add @xtreat/solid-iconify

2. Usage

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

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:

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 for unit and e2e tests. To run tests:

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:

import type {
  IconifyIconProps,
  IconifyConfig,
  // ...etc
} from "@xtreat/solid-iconify";

---

📚 Example

import Icon from "@xtreat/solid-iconify";

<Icon icon="mdi:home" width={48} color="#0078d4" />

---

💬 Feedback & Contributions

Issues and PRs are welcome! Open an issue or submit a pull request.

---

🔗 Links

• Iconify Icon Explorer
• SolidJS Docs
• Project Repository

---

🐞 Known Bugs

• Icon reactivity broken: Changing the icon prop does not always update the rendered SVG as expected.

---

📝 License

MIT © 2025 Xander Treat