with icons

1000 icons, each drawn once and rendered in 34 styles. The ink is currentColor, the grid 24x24, the default size 24. Site https://withicons.com · repo https://github.com/withevergrow/withicons · MIT. Detail lives in reference/; read the file a rule links to before going beyond the rule.

1. Pick the package

Every framework package, <with-icon> and the class loader carry all 34 styles (they fetch companions themselves). Only raw files are split: the newest styles' SVGs and node data are in @withicons/core-plus, soft3d and holiday, prebuilt SVGs and sprites in static-plus, classes in classes-plus / soft3d / holiday (so soft3d's SVGs and nodes are in @withicons/soft3d, its sprite sprite-soft3d.svg in @withicons/static-plus): see frameworks.md for any file's URL.

Every framework has the same props: size (24), color (currentColor; prefer CSS color on a parent), strokeWidth (line, duo, blueprint, sketch, kawaii only), absoluteStrokeWidth, title, className/class; the rest is spread onto the <svg>. The web component takes attributes (variant, not style; label, not title). Snippets per framework, the props table, CDN sizes and version pinning: reference/frameworks.md.

2. Pick the style

Six groups, named for what people make. Use ONE style per page or UI region (the only routine mix: line for inactive, solid for active). Each style is a subpath with the same export names: @withicons/react/solid, /clay, /christmas …

What are you making? (best first; full list in styles.md, MCP recommend_styles): app or website: line, duo, solid · slides: solid, duo, suite · SaaS landing page: bento, soft3d, duo · AI product: clay, liquid, chrome · premium: glass, luxe · playful: kawaii, plush, sticker · print: engrave, sketch, blueprint · a festival: its holiday style.

• Festivals: Diwali, Durga Puja, Holi -> rangoli (clean, brand-friendly) or utsav (ornate); Halloween -> halloween; Christmas -> christmas; Lunar New Year -> lunar; Valentine's, weddings -> valentine. Pair them with the 95 festival icons (categories indian-festivals, christmas, lunar-new-year, valentines, halloween: diya, red-lantern, jack-o-lantern …) and everyday ones (shopping-bag, tag). Switch festivals by palette (holi, diwali, nordic …: every colour in styles.md; CLI --colors "…", since --palette takes per-icon ids only).
• Avatars (category avatars, 40 avatar-*): people, animals, friendly monsters. In every person c1 is the skin and c2 the hair (or turban, cap), so one tone picker fits all (skin tones); offer several, never one default skin tone. Role-named styles keep the roles stable: plush, clay, pastel; duo or line for small UI.
• Duo has an accent colour (--with-duo-accent: the icon's badge, plus or slash, else an inner part like a bell's clapper) and two presets: "Duo with an accent" (--with-duo: #6B70F7; --with-duo-accent: #6B70F7, strokeWidth 1.5) works in every package; "Duo gradient" (lines swept indigo to pink) is made only in the studio (withicons.com/icons/<name>.html?style=duo#studio), whose downloads bake it into the file (no package or CLI API yet: use the downloaded file as an image). styles.md.
• Sizes: line and solid from 12px, duo 18px; everything else is illustration at 32px+ (luxe, skeuo, gothic, plush 48px).
• Colour: multi-colour styles paint CSS variables --with-<style>-<role> with defaults (role-named styles also give the outline its own --with-<style>-ink; elsewhere the ink is currentColor). For a brand colour set the icon's main role: npx withicons palettes <icon> --style <style> names it, and get / export take role flags (--c1, --tint …). For one exact hex across a set, use solid or line with color.
• Rich styles draw gradients in one <defs> (ids wg-<style>-<icon>-<n>, made unique per instance by every package).

Looks, minimum sizes, every variable, holiday palettes and Duo presets: reference/styles.md.

3. Names (never guess one)

• Canonical names are kebab-case (arrow-right); components are PascalCase, exported as ArrowRight and ArrowRightIcon.
• Aliases (bin, house, gear) resolve in name-based APIs (<with-icon name>, <Icon name>, resolve(), search, MCP) but are not exports: import { Bin } fails, use Trash.
• Look every name up before writing it (section 5) or read reference/icons.md (all 1000 names, categories, aliases). Common: delete/bin -> trash, gear -> settings, x/dismiss -> close, hamburger -> menu, house -> home, magnifier -> search, profile picture -> user-circle or an avatar-* icon.

4. Accessibility (every time)

1. Icon next to visible text: nothing to add; it is aria-hidden by default.
2. Icon-only button or link: name the control, not the icon: <button type="button" aria-label="Delete row"><Trash /></button>.
3. Meaningful standalone icon (status, rating): title="Error" (components) or label="Error" (web component).
4. <i class="with …"> has no semantics: add aria-hidden="true" and visible or .sr-only text.
5. Exported SVG files contain a <title>: next to text use aria-hidden="true" inline or alt="" on <img>.
6. Never rely on the icon alone; 3:1 contrast for meaningful icons; targets of at least 24x24 px (44 on touch) via padding.

More in reference/frameworks.md.

5. Find the right icon

• MCP (best for agents): remote https://withicons.com/mcp (about 1,000 requests per IP per 5 minutes, then HTTP 429), local and unlimited npx -y @withicons/mcp (prefer it for batch work). Tools: search_icons, get_icon, resolve_icon, recommend_styles (best styles for a job, a festival or an audience, with packages, presets and palettes), preview_icons (one labelled picture of icons x styles: look before you choose), animate_icon, export_icon, list_palettes, list_styles (grouped), list_categories; confirm with tools/list. Not connected? npx withicons init adds the skill and the server to the project's AI tools (--dry-run first).
• CLI npx withicons search "throw away" · HTTP https://withicons.com/api/search?q=throw+away&limit=5 (on a timeout retry once, or read https://withicons.com/icons.json) · offline reference/icons.md or import { search, resolve } from '@withicons/core'.
• One concept per query; if nothing fits, try a synonym, then the object you would draw, then browse the category.
• Trust confidence high and medium; low (reason "(related, low confidence)") is only related. Some words return nothing (shirt, pram) or only low matches (yoga -> dumbbell): pick the closest honest icon, label it in text, and never pass it off as exact. There are no brand or social logos: use a neutral stand-in (camera, play, message-circle, code) with the brand name as text or aria-label.

MCP client setup, every tool's arguments, the HTTP API, content gaps and search tips: reference/search.md.

6. Animate (optional, @withicons/motion)

Pure CSS (plus a tiny JS API) that wraps the element holding the icon, so it works with every style and package. Get paste-ready code from MCP animate_icon or npx withicons animate <name> --trigger hover --format react.

import '@withicons/motion/motion.css'   // presets
import '@withicons/motion/icons.css'    // every icon's tuned motion (or one CDN file per icon: dist/icons/<name>.css)
<span className="wm wm-loop" data-wm="loader"><Loader /></span>
<button className="wm-trigger" aria-label="Alerts"><span className="wm wm-hover" data-wm="bell"><Bell /></span></button>
<span className={'wm-swap wm-fx-morph' + (playing ? ' is-on' : '')}><Play className="wm-a" /><Pause className="wm-b" /></span>

• <with-icon> uses the motion attribute plus @withicons/motion/dist/element.js, never a .wm wrapper (its svg is in a shadow root). Wrappers are for inline SVG, components, live icons and <i> classes.
• Motion explains state or invites action; one or two loops per screen; no hover on touch (prefer wm-inview / wm-once). Reduced motion turns everything off. The accessible name stays on the button.
• 3D: in clay, glass, liquid, chrome, soft3d, luxe, skeuo, dock and plush the icon's motion plays in 3D (turns, lifts, lands). <with-icon variant="clay" motion="loop"> does it itself; wrappers add wm-3d. soft3d has 3-5 moves per icon (npx withicons motions <icon> --style soft3d, MCP animate_icon moves). Exports of a 3D style move in 3D too.
• Scroll-triggered in React and other frameworks: motion(el, name, { trigger: 'inview', style }) from @withicons/motion in an effect, m.destroy() on unmount (.wm-inview in markup alone does nothing; motion.md).

Triggers, presets, swaps, TypeScript casts, checking that it runs: reference/motion.md.

7. Files for slides, print, email, docs and social

When the result is a deck, document, print file, email or post, give FILES, not code (Node 18+, no browser):

npx withicons export truck package home --format svg-flat,png,pdf --out icons
npx withicons export bell --format gif --background "#ffffff" --out slides      # animated, loops forever
npx withicons export rocket --style luxe --format pptx-animated --background "#0f172a" --color "#ffffff"

MCP export_icon takes the same options in snake_case (out_dir on the local server). The remote server makes PNG and the other still formats itself (inline, base64) and answers gif, apng, pptx-animated and pptx-sheet with the npx withicons export … command to run.

• Slides and docs: png at 512 px, transparent, embedded as a picture (PNG, not SVG); design tools: svg-flat; print: pdf, eps or svg-flat (never PNG); email: PNG at 2x, hosted on your https URLs (never SVG); a moving icon: gif (plays in PowerPoint, Keynote, Google Slides, Gmail, Slack).
• Colours are baked in; a currentColor ink becomes black (role-named styles keep their own ink colour): on dark backgrounds pass --color "#ffffff" and the slide colour as --background (GIF), and pick an on-dark palette for multi-colour styles. Quote colours (# starts a comment).
• One look for many icons: role flags on one call (--c1, --tint …), since palette ids are per icon. Export one and look before the whole set.
• A whole style for designers or no-code: https://withicons.com/downloads/with-icons-<style>.zip (every SVG + an offline searchable viewer), with-icons-all.zip for every style. A festive campaign: export in its holiday style (--style rangoli).
• pptx-animated is one sample slide: for a deck insert GIFs. --padding, --size, --fps, --name and the rest: npx withicons export --help.

Formats per job, file names, GIF sizes, email HTML, print stroke weight: reference/files.md.

8. Live icons (content you set, @withicons/dynamic)

Up to 50 icons that draw a value inside: a calendar's date, a clock's time, a badge count, a battery level, a short label (max 4 characters; counts show "99+"). They render in every style.

<script src="https://cdn.jsdelivr.net/npm/@withicons/dynamic@latest/dist/cdn/lite.js"></script>
<with-live-icon name="calendar-date" today label="Today"></with-live-icon>
<with-live-icon name="bell-count" count="3" animate label="3 unread"></with-live-icon>

React / Vue: import { LiveIcon } from '@withicons/dynamic/react' (or /vue), <LiveIcon name="bell-count" count={n} animate />. Pure function: render(name, params, style) from @withicons/dynamic (never reads the clock: pass now()). Change a value by setting the attribute or prop; in React never change the key to replay. Vite needs worker: { format: 'es' }. Every live icon with its params, sizes and recipes: reference/live.md.

9. Loaders (loading states, @withicons/loaders)

Animated loaders in every style: everyday spinners and dots, creative ones (ai-sparkle, rocket, coffee, atom …), festival ones (diya, fireworks, ghost, lantern …) and morph sequences of library icons (file → cloud → check). Each is one self-contained SVG animated with CSS: no JavaScript, 60 fps, slows for reduced motion, labelled "Loading". Cheapest form:

<img src="https://cdn.jsdelivr.net/npm/@withicons/loaders@latest/dist/svg/line/spinner.svg" width="32" height="32" alt="Loading">

Colour, speed, custom sequences, a finished state: the tag (or Loader / Morph from @withicons/loaders/react or /vue).

<script src="https://cdn.jsdelivr.net/npm/@withicons/loaders@latest/dist/cdn/loaders.js"></script>
<with-loader name="orbit" variant="glass" color="#7c5cff" speed="1.2"></with-loader>
<with-loader morph="file,cloud-upload,check-circle" effect="slide-up"></with-loader>  <!-- then el.done() -->

Morph items are icon names (even rocket, download, gift, which are loaders too); write loader:<name> to put a loader in the chain (since 0.6.0).

Pick by what is loading (MCP get_loader(query) answers with the URL and code). Every name and what it says: reference/loaders.md.

10. Pitfalls

• The generic <Icon name=…> renders line at once and loads other styles on first use (React/Solid: wrap in <Suspense>; sync SSR: await preloadStyles(...) first): only for truly dynamic names; otherwise named imports.
• <img src="….svg"> cannot follow currentColor and renders black; inline, use a component, sprite or classes.
• Sprites must be served from your own origin (cross-origin <use href> is blocked).
• Icon classes are CSS masks: multi-colour variables only work in components, <with-icon>, sprites or with-icons.js.
• From a CDN load only what the page shows (cdn.js, with-loader.js, lite.js); never with-all.css or @withicons/web/full on a real page. @latest follows releases; pin one version for a fixed look. React, Vue or Solid from an ESM CDN: name the icons (https://esm.sh/@withicons/react?exports=Home,Search), never a bare style URL.
• Svelte 4 does not forward on:click to the icon (wrap it in a button); Angular name= needs provideWithIcons(...).
• Right-to-left: mirror only directional icons (with-rtl, mirror-rtl, or a :dir(rtl) CSS rule on components).
• Don't mix with icons and another set in one UI region; replace the old icons one-for-one using search.

Details for each: reference/frameworks.md.

11. From a chat assistant (no tools, no install)

Briefs from withicons.com's "Ask AI" buttons start by sending you here and carry a MY TASK: line (find, code, set, fit, slides). Do that task, search before naming anything, link https://withicons.com/icons/<name>.html for every pick, and give code to developers and the page's Copy image / SVG / PNG buttons to everyone else. What each task should return: reference/chat.md.