@tokens-studio/icons-webcomponents

A comprehensive, type-safe icon library as web components for use in any framework or vanilla JavaScript.

Features

• ✅ 344+ icons available as web components
• ✅ TypeScript support with full type definitions
• ✅ Framework agnostic - works with React, Vue, Angular, Svelte, or vanilla JS
• ✅ Tree-shakeable - import only what you need
• ✅ AI-friendly - comprehensive types and metadata for AI assistants
• ✅ Customizable - style with CSS custom properties

Installation

npm install @tokens-studio/icons-webcomponents

Usage

Basic Usage

<!-- Import the icon -->
<script type="module">
	import '@tokens-studio/icons-webcomponents/Plus';
</script>

<!-- Use it in your HTML -->
<icon-plus></icon-plus>

TypeScript Usage

// Import specific icon
import '@tokens-studio/icons-webcomponents/Plus';

// Or import all icons
import * as Icons from '@tokens-studio/icons-webcomponents';

// Use types for type-safe icon names
import type {
	IconName,
	IconComponentName,
} from '@tokens-studio/icons-webcomponents';

const iconTag: IconName = 'icon-plus';
const componentName: IconComponentName = 'Plus';

React Usage

import '@tokens-studio/icons-webcomponents/Plus';

function MyComponent() {
	return <icon-plus></icon-plus>;
}

Vue Usage

<template>
	<icon-plus></icon-plus>
</template>

<script setup>
import '@tokens-studio/icons-webcomponents/Plus';
</script>

Styling

Icons use currentColor for stroke/fill, so you can style them with CSS:

icon-plus {
	color: #3b82f6;
	width: 32px;
	height: 32px;
}

/* Or use CSS custom properties */
icon-plus {
	--icon-width: 32px;
	--icon-height: 32px;
	color: #3b82f6;
}

Type Safety

Icon Name Types

import type {
	IconName,
	IconComponentName,
} from '@tokens-studio/icons-webcomponents';

// Type-safe icon tag names
const tag: IconName = 'icon-plus'; // ✅ Valid
const invalid: IconName = 'icon-invalid'; // ❌ TypeScript error

// Type-safe component names
const component: IconComponentName = 'Plus'; // ✅ Valid

Icon Maps

import {
	iconTagToComponentMap,
	iconComponentToTagMap,
} from '@tokens-studio/icons-webcomponents';

// Convert tag name to component name
const componentName = iconTagToComponentMap['icon-plus']; // 'Plus'

// Convert component name to tag name
const tagName = iconComponentToTagMap['Plus']; // 'icon-plus'

Icon Manifest

Access the complete icon manifest programmatically:

import manifest from '@tokens-studio/icons-webcomponents/manifest';

console.log(manifest.total); // 344
console.log(manifest.icons); // Array of all icons with metadata

Each icon in the manifest includes:

• name: PascalCase component name (e.g., "Plus")
• tag: Web component tag name (e.g., "icon-plus")
• keywords: Search keywords for the icon
• importPath: Full import path
• importStatement: Ready-to-use import statement
• componentImport: Component import statement

Available Icons

All icons are available with their kebab-case tag names. For example:

• icon-plus → <icon-plus></icon-plus>
• icon-user → <icon-user></icon-user>
• icon-settings01 → <icon-settings01></icon-settings01>

Many icons also have "filled" variants:

• icon-plus (outline)
• icon-plus-filled (filled/solid)

AI Assistant Support

This package is designed to be AI-friendly with:

1. Comprehensive TypeScript types - All icon names are typed
2. Icon manifest - JSON file with all icon metadata
3. JSDoc comments - Each icon component has documentation
4. Type exports - Easy to discover available icons programmatically

AI assistants can:

• Discover all available icons via types
• Get icon metadata from the manifest
• Understand icon usage through JSDoc
• Provide type-safe suggestions

Development

Building

npm run build

Regenerating Icons

npm run regenerate

This will:

1. Clean existing icons
2. Convert SVG assets to React components (via SVGR)
3. Convert React components to web components
4. Generate type definitions and manifest

License

[Your license here]