# 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
# fetch the manifest once, filter client-side
curl "https://thesvg.org/api/registry.json"
# direct SVG
curl "https://thesvg.org/icons/openai/default.svg"
```

### 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

thesvg ships as a fully static site. There is no dynamic search endpoint. Fetch the manifest once and filter client-side.

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

### Direct SVG (CDN)
```
GET /icons/{slug}/{variant}.svg
```
Returns raw SVG with `image/svg+xml` content type, served from Cloudflare CDN.

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

### Icon Manifest
```
GET /api/registry.json
```
Returns the full manifest as `{ total, icons: [...] }`. Each icon has: `slug`, `title`, `aliases`, `categories`, `hex`, `url`, `license`, `variants` (array of variant keys). Use this to power search, filtering, and listing.

### Categories
```
GET /api/categories.json
```
Returns all categories with icon counts as `{ categories: [{ name, count }, ...] }`.

### jsDelivr Mirror

For high-traffic apps, use jsDelivr instead of `thesvg.org` directly:
```
https://cdn.jsdelivr.net/gh/glincker/thesvg@main/src/data/icons.json
https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/{slug}/{variant}.svg
```
`src/data/icons.json` is the source-of-truth manifest with all per-icon fields including `dateAdded` and `collection`.

### Roadmap

A gated, token-based API with relevance search and webhooks is planned at `api.thesvg.org`.

## 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
- Compare Libraries: https://thesvg.org/compare
- Legal: https://thesvg.org/legal
- Submit Icon: https://thesvg.org/submit
- Contact: https://thesvg.org/contact