# theSVG - Full LLM Context

> The largest open-source brand SVG icon library. 4,000+ brand icons with multi-variant support.

## Overview

theSVG (thesvg.org) is a free, open-source library of brand SVG icons for developers and designers. Every icon includes metadata (brand name, hex color, categories, license, website URL, brand guidelines) and up to 7 SVG variants per brand.

## Quick Start

### Install via npm
```bash
npm install thesvg
# or
npm install @thesvg/icons
# or
npm install @thesvg/react
```

### Use via CDN (no install)
```html
<img src="https://thesvg.org/icons/github/default.svg" width="24" alt="GitHub" />
```

### Use via CLI
```bash
npx @thesvg/cli add github
npx @thesvg/cli search "ai"
```

### Use via API
```bash
curl "https://thesvg.org/api/registry/github"
curl "https://thesvg.org/api/registry?q=openai&limit=5"
```

### Use via MCP Server (AI Assistants)
```json
{
  "mcpServers": {
    "thesvg": {
      "command": "npx",
      "args": ["@thesvg/mcp-server"]
    }
  }
}
```

## Packages

| Package | Description | Install |
|---------|-------------|---------|
| `thesvg` | All icons, one package | `npm i thesvg` |
| `@thesvg/icons` | Tree-shakeable icon data | `npm i @thesvg/icons` |
| `@thesvg/react` | Typed React components | `npm i @thesvg/react` |
| `@thesvg/cli` | CLI for adding icons | `npx @thesvg/cli add {slug}` |
| `@thesvg/mcp-server` | MCP server for AI agents | `npx @thesvg/mcp-server` |

## Icon Data Schema

```typescript
interface IconEntry {
  slug: string;            // kebab-case identifier (e.g. "github")
  title: string;           // display name (e.g. "GitHub")
  aliases: string[];       // alternative names
  hex: string;             // brand color without # (e.g. "181717")
  categories: string[];    // tags (e.g. ["Software", "Platform"])
  variants: {
    default: string;       // always present - URL path to SVG
    mono?: string;         // single color variant
    light?: string;        // white variant for dark backgrounds
    dark?: string;         // dark variant for light backgrounds
    wordmark?: string;     // full logo with text
    wordmarkLight?: string;
    wordmarkDark?: string;
  };
  license: string;         // e.g. "CC0-1.0", "MIT", "Fair Use"
  url?: string;            // brand website
  guidelines?: string;     // brand guidelines URL
}
```

## API Reference

Base URL: `https://thesvg.org`

### Direct SVG (CDN)
```
GET /icons/{slug}/{variant}.svg
```
Returns raw SVG with `image/svg+xml` content type. Cached 24h.

Example: `https://thesvg.org/icons/github/default.svg`

### Search Icons
```
GET /api/registry?q={query}&category={category}&limit={number}
```
Returns JSON array of matching icons with metadata.

Parameters:
- `q` (optional) - Search query, fuzzy matches name/slug/aliases
- `category` (optional) - Filter by category name
- `limit` (optional) - Max results (default: 50, max: 200)

### Get Single Icon
```
GET /api/registry/{slug}
```
Returns full metadata including inline SVG content for all variants.

### List Categories
```
GET /api/categories
```
Returns all categories with icon counts.

### jsDelivr CDN
```
https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/{slug}/{variant}.svg
```

## Framework Examples

### React (CDN approach - recommended for performance)
```tsx
function BrandIcon({ slug, size = 24 }: { slug: string; size?: number }) {
  return (
    <img
      src={`https://thesvg.org/icons/${slug}/default.svg`}
      width={size}
      height={size}
      alt={slug}
    />
  );
}
```

### React (Component approach)
```tsx
import { Github } from "@thesvg/react";

<Github width={24} height={24} className="text-gray-900" />
```

### Vue
```vue
<template>
  <img :src="`https://thesvg.org/icons/${slug}/default.svg`" :width="size" :alt="slug" />
</template>
```

### HTML with dark mode
```html
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://thesvg.org/icons/github/light.svg" />
  <img src="https://thesvg.org/icons/github/dark.svg" alt="GitHub" width="24" />
</picture>
```

### Markdown
```markdown
![GitHub](https://thesvg.org/icons/github/default.svg)
```

## Variants Explained

| Variant | Key | Best for |
|---------|-----|----------|
| Default | `default` | General use, brand's primary colors |
| Mono | `mono` | Monochrome UIs, inherits `currentColor` |
| Light | `light` | Dark backgrounds (white fill) |
| Dark | `dark` | Light backgrounds (dark fill) |
| Wordmark | `wordmark` | Full logo with brand text |
| Wordmark Light | `wordmarkLight` | Wordmark for dark backgrounds |
| Wordmark Dark | `wordmarkDark` | Wordmark for light backgrounds |

Not every icon has all variants. `default` is always present.

## Categories (56 total)

AI, Analytics, Authentication, Automotive, Aviation, Banking, Browser, Cloud, CMS, Community, Crypto, Database, Design, Devtool, Education, Editor, Entertainment, Finance, Food, Framework, Gaming, Google, Hardware, Hosting, IoT, Language, Library, Linux, Logistics, Media, Messaging, Music, Network, Payment, Photography, Platform, Privacy, Productivity, Religion, Science, Security, Self-Hosted, Shopping, Social, Software, Sports, Storage, Streaming, Telecom, Travel, and more.

## Statistics

- 4,000+ brand icons
- 56 categories
- 8,400+ total SVG variants
- 869 icons with verified brand guidelines links
- All icons have license metadata
- Zero runtime dependencies (React is peer dep for @thesvg/react)

## License

MIT for the codebase and tooling. Brand icons are property of their respective trademark holders, provided under nominative fair use for identification purposes.

## Links

- Website: https://thesvg.org
- GitHub: https://github.com/glincker/thesvg
- npm: https://www.npmjs.com/package/thesvg
- API Docs: https://thesvg.org/api-docs
- Compare Libraries: https://thesvg.org/compare
- Legal: https://thesvg.org/legal
- Submit Icon: https://thesvg.org/submit
- Contact: https://thesvg.org/contact