islamic-icons

A tree-shakeable React component library of Islamic SVG icons.
Built with TypeScript, Vite, and full accessibility support.

Installation

npm install islamic-icons
# or
yarn add islamic-icons
pnpm add islamic-icons

Requirements: Node.js >= 18, React 16.8+ (web); for React Native / Expo, also install react-native-svg and use the /native entry (see below).

Security and supply-chain: this package has no production dependencies; only peer deps (React, react-native-svg). For Socket.dev and similar alerts, see SECURITY.md.

| Environment | Import from | |--------------------|--------------------------| | Web (React DOM) | 'islamic-icons' | | React Native/Expo | 'islamic-icons/native' |

Usage

Import only the icons you need for optimal bundle size (tree-shaking). Use the component name from the package, not the source SVG path:

// ✅ Correct: import by icon name from the package
import { TasbihIcon, DomeIcon, CrescentIcon } from 'islamic-icons';

// ❌ Don’t: import from internal source paths like islamic-icons/icons/source/...

Example:

import { CrescentIcon, StarIcon } from 'islamic-icons';

function App() {
  return (
    <>
      <CrescentIcon size={24} aria-label="Crescent moon" />
      <StarIcon size={32} color="#eab308" />
    </>
  );
}

Props

All icons accept the same props (extends SVGProps<SVGSVGElement>):

| Prop | Type | Default | Description | |---------------|------------------|------------|--------------------------------------| | size | number \| string | 24 | Width and height (e.g. 32 or "2rem") | | color | string | currentColor | Fill color (theming-friendly) | | className | string | — | CSS class | | style | object | — | Inline styles | | aria-label | string | — | Accessible name (recommended for meaningful icons) | | title | string | — | Tooltip / title |

When neither aria-label nor title is set, icons get aria-hidden="true" so they are treated as decorative.

Examples

// Size and color
<CrescentIcon size={48} color="var(--primary)" />

// Custom class and style
<StarIcon className="my-icon" style={{ filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.2))' }} />

// Accessible (e.g. in buttons)
<button>
  <CrescentIcon size={20} aria-label="Islamic symbol" />
  <span>Symbol</span>
</button>

Icon categories

• Mosque & architecture – domes, minarets, arches
• Religious symbols – crescent, star, mosque lamp
• Prayer items – prayer beads, prayer rug, Quran stand
• Hands / prayer positions – takbir, ruku, sujud, tashahhud, salam
• Direction – Qibla
• Phrases – Bismillah, Alhamdulillah, etc. (as SVGs)

More icons are added over time. Run the documentation site (npm run docs, then open http://localhost:5174), the demo, or Storybook to see what’s available.

React Native / Expo

Use the /native subpath so Metro bundles the React Native build (no pre-bundled React):

import { TasbihIcon, DomeIcon, CrescentIcon } from 'islamic-icons/native';

Install the peer dependency:

npm install react-native-svg
# or
yarn add react-native-svg

• Icons use react-native-svg (Svg, Path, Circle, Image, etc.). Icons with embedded raster (e.g. Tasbih) use Image with the same data URI.
• Same props: size, color, style, aria-label (and standard react-native-svg props where applicable).

Upgrading from an older version? See MIGRATION.md for the switch to islamic-icons/native on React Native.

Icon sources (web vs RN)

• Web: Source SVGs are used as-is; embedded <image> (e.g. PNG via data URI) is kept so icons like Tasbih render correctly.
• RN: The same sources are converted to react-native-svg; vector elements become Path/Circle/Rect, and <image> becomes Image with the same href, so raster icons also work.

Development

Node: Use Node 18 or newer (see .nvmrc for recommended version).

# Install dependencies
npm install

# Optimize SVG sources (icons/source/**/*.svg)
npm run optimize:svgs

# Generate React components from SVGs (web + native)
npm run generate:icons
npm run generate:icons:rn

# Type check
npm run typecheck

# Lint and type check
npm run lint
npm run typecheck

# Build library – web (dist/web) and React Native (dist/native)
npm run build
npm run build:native

# Dev demo
npm run dev

# Storybook
npm run storybook

Adding new icons

1. Add SVG files under icons/source/ (e.g. icons/source/symbols/mosque-lamp.svg).
2. Use kebab-case.svg; the script will create MosqueLampIcon.
3. Run npm run optimize:svgs, then npm run generate:icons and npm run generate:icons:rn.
4. Web exports live in src/index.ts; native in src/native/index.ts.

Tech stack

• Build: Vite, SWC (React)
• Language: TypeScript
• Output: ESM + CommonJS, tree-shakeable
• Icons: SVG optimized with SVGO, generated via @svgr/core
• Docs: Storybook

Publishing

• npm 403 (2FA required): See docs/PUBLISH.md for enabling 2FA or using an automation token.
• Create the public GitHub repo: See docs/GITHUB_REPO.md for creating the repo and pushing.

Step-by-step setup (first time)

1. Clone and install

   cd islamic-icons && npm install

2. Add SVG sources
   Place .svg files under icons/source/<category>/ (e.g. icons/source/symbols/mosque-lamp.svg). Use kebab-case names.

3. Optimize SVGs (optional)

   npm run optimize:svgs

4. Generate React components

   npm run generate:icons

   This creates/updates src/icons/*.tsx and src/icons/index.ts.

5. Build the package

   npm run build

   Output is in dist/ (ESM + CJS + types).

6. Publish to NPM

   npm run prepublishOnly   # builds web + native
   npm login
   npm publish

   Ensure package.json has correct name, version, and repository before publishing.

Security

• Vulnerability reports: See SECURITY.md.
• Consumers: Keep react and react-dom up to date; the library does not execute remote code or use eval.

License

MIT