Weasel Icons

Icons that overreact beautifully. Stateful React SVG icons with smooth transitions and optional continuous behavior.

Version 0.11.0 adds an optional multi-agent customization skill and CLI with version-matched editable source.

Version 0.10.0 contains 874 icons, adding 200 across documents, collaboration, spatial tools, media, commerce, transport and characters. Existing released icons retain their APIs.

Version 0.7.0 contained 469 icons; 0.6.0 contained 265 icons.

Version 0.14.4

Restores Cauldron’s earlier short steam curls and gentle drifting motion while keeping the refined bowl, rim and bubbling effect. Public states and shared props remain unchanged. The customization CLI includes the matching editable source.

Version 0.14.3

Refines Jack O’ Lantern with clear solid carving and a rooted flame, gives Cauldron bubbles and steam that emerge from its opening, and improves Witch Hat’s buckle and connected tipping motion. Casting remains a one-shot gesture. Public states, shared props and the 1,034-icon collection remain unchanged. The customization CLI includes the matching editable source.

Version 0.14.2

Refines Mummy with a clearer eye band and attached fluttering wrap, keeps Tombstone and its RIP lettering fixed while bats pass above it, and gives Candy Corn a rounded silhouette with a distinct concave bite. Public state names, shared props and the 1,034-icon collection remain unchanged. The customization CLI includes the matching editable source.

Version 0.14.1

Refines Vampire with a fixed face, solid hair and mouth, and white fangs; gives Frankenstein swept hair and attached ears. Repairs Can, Fountain, Grill Fork and Rat motion. The customization guide now covers stable anatomy and deliberate outline, ink and neutral paint roles. Public state names and shared props stay compatible; the collection remains at 1,034 icons.

Version 0.14.0

Adds 10 Halloween icons with three typed states each, bringing the collection to 1,034: cauldron, coffin, witch hat, potion bottle, Frankenstein, tombstone, vampire, mummy, spider web and candy corn. Includes vampire-to-bat transformation, one-shot hat casting, bats above the tombstone and a spider walking out of its web. The existing jack-o’-lantern’s lit state now turns its stalk into an attached flickering flame. Existing state names and shared props remain compatible.

Version 0.13.0

Adds 100 stateful icons, bringing the collection to 1,024, with three typed states per new icon. Includes the reviewed money-bag coin exit, volcano smoke and eruption, pouring droplets, folding chair and rolling wheels. Existing exports and props remain compatible. The customization CLI includes the new icons and their version-matched editable source.

Version 0.12.0

Adds 50 icons, bringing the collection to 924, with three typed states for each new icon. The release includes the revised gearbox track, cricket bat, melting snowman, roller-skate braking, side-flowering cactus and flowing hydrant. The application supplies state facts; animation does not infer completion.

Representative imports include BarrierGateIcon, PliersIcon, CraneIcon, ButterflyIcon, PrismIcon and WheelIcon, available from the root or matching subpaths.

Neutral occlusion uses --weasel-surface (white by default). Set it to the host surface on dark or coloured backgrounds.

Install

npm install weasel-icons
# or
pnpm add weasel-icons

Supports React / React DOM 18.3 or 19. Motion is installed as a dependency. No stylesheet, provider, Tailwind, or Next.js dependency is required. The package is ESM with TypeScript declarations and per-icon exports.

Customize with your coding agent

npm install weasel-icons
npx weasel-icons setup

Choose all the agents you use: Codex, Claude Code, Antigravity IDE/App, Antigravity CLI or Cursor. Personal setup is the default and stays outside your repository. Then ask your agent: “Use weasel-customize to add a state to my icon.” Setup installs instructions; it does not launch an AI, share conversations or generate code by itself.

For non-interactive setup, or to add another agent later:

npx weasel-icons setup --agent codex,claude-code --scope user

Use --scope project for a team skill checked into this app. Existing or modified skill entries are preserved. Restart/reload the agent if the skill does not appear.

The agent reads the full guide from the installed package and copies only the selected icon and its required runtime:

npm exec --no -- weasel-icons skills get customize
npm exec --no -- weasel-icons icons list refresh
npm exec --no -- weasel-icons icons add refresh --dir src/components/weasel

Declare motion as a direct dependency when using copied source (use the dependency range from the installed weasel-icons/package.json). Copied TypeScript needs a compiler target of ES2015+ or downlevelIteration. Import the customized component from your local source. Other icons can keep their npm imports. Existing custom files are never overwritten; conflicting runtime versions require a separate destination. Keep the copied license notices with redistributed source.

The CLI uses bundled source and makes no network requests. It requires Node 22.13 or newer; the icon components themselves remain React 18.3/19 compatible. Personal setup paths are agent-specific: Codex ~/.agents/skills, Claude Code ~/.claude/skills, Antigravity IDE/App ~/.gemini/config/skills, Antigravity CLI ~/.gemini/antigravity-cli/skills, Cursor ~/.cursor/skills. Project paths are .agents/skills for Codex/Antigravity, .claude/skills for Claude Code and .cursor/skills for Cursor.

To remove an unchanged discovery entry, run npx weasel-icons setup --agent codex,claude-code --remove. Modified entries and customized app source are preserved. Re-run setup to restore an entry. The detailed guide updates when the app's Weasel package is updated.

Use

import { DogIcon } from 'weasel-icons';
// Alternatively: import { DogIcon } from 'weasel-icons/dog';

export function HappyDog() {
  return <DogIcon state="happy" alive size={32} color="#75002f" accentColor="#ff5ca3" />;
}

Import only the icons you use. Compatible production bundlers can tree-shake the others.

Change a state

'use client';

import { useState } from 'react';
import { HeartIcon } from 'weasel-icons';

export function LikeButton() {
  const [liked, setLiked] = useState(false);
  return (
    <button aria-label="Like" aria-pressed={liked} onClick={() => setLiked(!liked)}>
      <HeartIcon state={liked ? 'liked' : 'unliked'} size={24} />
    </button>
  );
}

The existing SVG smoothly transitions when state changes, including during an unfinished transition. Use your own button or wrapper for hover, click, keyboard, and sequence behavior. Next.js App Router client boundaries are preserved in the package.

Icons and props

Exports include: DogIcon, MonkeyIcon, HeartIcon, ShipIcon, RocketIcon, SearchIcon, BellIcon, DownloadIcon, ShieldIcon, CursorIcon, ClapperboardIcon, PlugIcon, BulbIcon, AlertIcon, BadgeCheckIcon, ReplaceIcon, DeleteIcon, SwapIcon, SparklesIcon, SparkleIcon, StarIcon, WaveIcon, RefreshIcon, CopyIcon, EyeIcon, LinkIcon, CheckIcon, and CloseIcon. Each icon exports its own state type and list, for example DogState and dogStates, or BadgeCheckState and badgeCheckStates. TypeScript autocompletion shows the valid states for each icon.

Added in 0.10.0

New exports include FilePlayIcon, FileSignalIcon, FileSlidersIcon, FileAxis3dIcon, CloudSyncIcon, UserShieldIcon and SnailIcon, from the root or their individual subpaths. Most new icons expose three states; File Play exposes ready, playing, paused, buffering and ended. The application supplies playback and result states. Snail exposes still, feelers and retracted, with feeler exploration and a retained shell withdrawal. Its shell uses --weasel-surface (white by default) for occlusion; set that variable to match a non-white host surface.

Added in 0.9.0

New exports include ToolCaseIcon (closed, open), LampFloorIcon (off, lit), TicketValidationIcon (unchecked, valid, invalid) and BanknoteTransferIcon (outgoing, incoming, declined). Import them from the root or their subpaths, such as weasel-icons/tool-case. Each exports its state list and type.

Tool Case opens its lid before exposing the tools, with visibility tied to the lid's actual pose so interruptions retain clearance. The application supplies every state; motion does not determine payment or validation outcomes.

Added in 0.8.0

FuelIcon, BrickWallIcon, BlocksIcon, DiceIcon, TargetIcon, BadgePercentIcon, WebhookIcon, InfinityIcon, FootprintsIcon and BotIcon are available from the main export and their individual subpaths, such as weasel-icons/webhook. Each exports its own state list and type. Webhook delivery follows its path from the currently visible packet position.

Puppy (DogIcon) retains waiting, sniffing, happy and guilty, its neutral outline, and all existing colour props. Living motion uses a restrained gesture per state; alive={false} and reduced motion settle to the existing expressions.

Added in 0.6.0

• Status & confirmation: CircleCheckIcon, CircleXIcon, CircleAlertIcon, CirclePlusIcon, CircleMinusIcon, SquareCheckIcon, CheckCheckIcon, ListChecksIcon, ClipboardCheckIcon, CalendarCheckIcon, ShieldCheckIcon, BanIcon.
• Money & business: BanknoteIcon, CoinsIcon, PiggyBankIcon, LandmarkIcon, BuildingIcon, StoreIcon, BriefcaseIcon, IdCardIcon, HandshakeIcon, CalculatorIcon.
• People & support: UserCogIcon, HeadsetIcon, MessageSquareIcon, GraduationCapIcon, TrophyIcon, AwardIcon.
• Tools & data: WrenchIcon, HistoryIcon, ServerIcon, CloudUploadIcon, GaugeIcon, ZoomInIcon, PaletteIcon, BrainIcon, LocateIcon, MapIcon.
• Places & things: PlaneIcon, CarIcon, UtensilsIcon, ShoppingBasketIcon, PinIcon, FlameIcon, DropletIcon, AlarmClockIcon.
• Controls: CirclePlayIcon, ArrowUpDownIcon, GripVerticalIcon, ChevronsUpDownIcon.

Added in 0.5.0

• Status: NetworkIcon (offline/connecting/online), SignalIcon (weak/searching/strong), BatteryIcon (low/charging/full), ToggleIcon (off/switching/on), HourglassIcon (idle/waiting/done), CompassIcon (idle/locating/located).
• Actions: TrashIcon (idle/emptying/emptied), ZapIcon (idle/boosting/boosted, with an accent energy fill), BugIcon (idle/debugging/fixed).

Added in 0.4.0

• Editing: UndoIcon, RedoIcon, CropIcon, ScissorsIcon, PaperclipIcon, EraserIcon, BrushIcon, HighlighterIcon.
• Layouts: PanelLeftIcon, PanelRightIcon, ColumnsIcon, RowsIcon, TableIcon, KanbanIcon, AppWindowIcon, PictureInPictureIcon.
• Files: FolderOpenIcon, FolderPlusIcon, FilePlusIcon, FileCheckIcon, ArchiveIcon, InboxIcon, HardDriveIcon, PrinterIcon.
• Devices: BluetoothIcon, CastIcon, MonitorIcon, SmartphoneIcon, PowerIcon, FingerprintIcon, ScanQrIcon, ScanFaceIcon.
• Media: SkipForwardIcon, SkipBackIcon, RewindIcon, FastForwardIcon, RepeatIcon, ShuffleIcon, HeadphonesIcon, RadioIcon.
• Collaboration: ThumbsUpIcon, ThumbsDownIcon, UserPlusIcon, UserMinusIcon, AtSignIcon, ReplyIcon, ForwardIcon, FlagIcon.
• Data & commerce: ChartBarIcon, ChartLineIcon, ChartPieIcon, TrendingUpIcon, ReceiptIcon, TagIcon, GiftIcon, TicketIcon.

Each addition supports the same props and exports its typed state list. The application supplies pending and result states; the animation never decides completion.

Added in 0.3.0

| Icon | States | Intended use | | --------------------- | ------------------------------------ | --------------------------------------------------- | | HomeIcon | idle, entering, active | Navigation: Home link in a header or sidebar | | MenuIcon | closed, hover, open | Navigation: Collapsed mobile navigation | | PlusIcon | idle, hover, pressed | Actions: Create item or increase quantity | | MinusIcon | idle, hover, pressed | Actions: Decrease quantity or remove a row | | ChevronDownIcon | collapsed, hover, expanded | Navigation: Closed disclosure or select menu | | ChevronRightIcon | idle, advancing, arrived | Navigation: Next step or drill into a row | | ChevronLeftIcon | idle, returning, arrived | Navigation: Previous page or back in a wizard | | ChevronUpIcon | collapsed, hover, expanded | Navigation: Closed upward popover | | ArrowRightIcon | idle, moving, arrived | Navigation: Next page or primary landing-page CTA | | ArrowLeftIcon | idle, moving, arrived | Navigation: Back navigation | | ArrowUpIcon | idle, moving, arrived | Navigation: Scroll to top or move a row upward | | ArrowDownIcon | idle, moving, arrived | Navigation: Scroll down or move a row downward | | ExternalLinkIcon | idle, opening, opened | Navigation: Open external resource from blog or app | | MoreHorizontalIcon | closed, opening, open | Actions: Overflow action menu closed | | MoreVerticalIcon | closed, opening, open | Actions: Row overflow menu closed | | UserIcon | idle, loading, active | Accounts: Profile or account entry | | UsersIcon | idle, inviting, joined | Accounts: Team or member list | | SettingsIcon | idle, adjusting, applied | Accounts: Open preferences | | LogInIcon | idle, entering, signed-in | Accounts: Sign-in action | | LogOutIcon | idle, leaving, signed-out | Accounts: Sign-out action | | LockIcon | locked, unlocking, unlocked | Security: Protected or private content | | KeyIcon | idle, turning, unlocked | Security: Credentials or access-key action | | InfoIcon | idle, revealing, open | Status: Information tooltip trigger | | MailIcon | unread, opening, read | Communication: Unread email or inbox | | SendIcon | idle, sending, sent | Communication: Submit message or contact form | | MessageCircleIcon | idle, typing, received | Communication: Conversation or comment entry | | PhoneIcon | idle, ringing, connected | Communication: Start a phone call | | VideoIcon | off, connecting, on | Media: Camera is disabled | | MicIcon | muted, listening, recording | Media: Microphone is muted | | PencilIcon | idle, writing, saved | Editing: Edit article or field | | FileTextIcon | idle, reading, complete | Files: Document or blog post link | | FileIcon | idle, creating, ready | Files: File picker or file row | | FolderIcon | closed, opening, open | Files: Closed folder or collapsed collection | | SaveIcon | idle, saving, saved | Editing: Save document or preferences | | UploadIcon | idle, uploading, complete | Files: Upload media or attachment | | ClipboardIcon | idle, checking, complete | Files: Checklist or review queue | | BookmarkIcon | unsaved, saving, saved | Content: Save blog post or resource | | BookOpenIcon | idle, reading, finished | Content: Documentation or article reading entry | | ImageIcon | idle, loading, loaded | Content: Image picker or media placeholder | | CameraIcon | idle, focusing, captured | Media: Take a photo or avatar picture | | ShareIcon | idle, sharing, shared | Content: Share article or app content | | CalendarIcon | idle, selecting, selected | Time: Date picker or event link | | ClockIcon | idle, running, paused | Time: Time or recent activity | | TimerIcon | idle, running, finished | Time: Start a countdown | | MapPinIcon | idle, locating, located | Location: Address or location entry | | GlobeIcon | idle, connecting, online | Location: Language or worldwide availability | | CircleHelpIcon | idle, asking, answered | Status: Help or FAQ trigger | | PlayIcon | idle, hover, pressed | Media: Start media or a tutorial | | PauseIcon | idle, hover, pressed | Media: Pause media or a task | | VolumeIcon | muted, low, high | Media: Audio muted | | MusicIcon | idle, playing, paused | Media: Music or audio track | | SunIcon | idle, rising, bright | Appearance: Light theme or daylight | | ShoppingCartIcon | empty, adding, filled | Commerce: Cart has no selected items | | ShoppingBagIcon | empty, packing, packed | Commerce: Shopping bag or checkout entry | | CreditCardIcon | idle, processing, approved | Commerce: Payment method selection | | WalletIcon | closed, opening, open | Commerce: Wallet or balance entry | | PackageIcon | sealed, opening, open | Commerce: Shipment or package row | | TruckIcon | idle, delivering, delivered | Commerce: Delivery option or shipment | | FilterIcon | idle, filtering, filtered | Controls: Filter options available | | SlidersIcon | idle, adjusting, applied | Controls: Open tuning or adjustment controls | | LayoutGridIcon | idle, reordering, ordered | Controls: Grid view or app launcher | | LayoutDashboardIcon | idle, loading, ready | Controls: Dashboard navigation | | ListIcon | idle, sorting, sorted | Controls: List view or item collection | | LayersIcon | stacked, separating, separated | Controls: Layer stack or grouped content | | MaximizeIcon | idle, expanding, expanded | Controls: Enter fullscreen or expand preview | | MinimizeIcon | idle, contracting, contracted | Controls: Exit fullscreen or collapse preview | | CodeIcon | idle, compiling, ready | Development: Code sample or developer feature | | TerminalIcon | idle, running, complete | Development: Open command prompt or CLI example | | DatabaseIcon | idle, syncing, synced | Development: Data store or record source | | WifiIcon | offline, connecting, connected | Connectivity: No wireless connection | | CloudIcon | idle, syncing, synced | Connectivity: Cloud files or remote storage | | MoonIcon | idle, setting, asleep | Appearance: Dark theme or quiet hours |

New icons also expose per-icon imports such as weasel-icons/menu, weasel-icons/upload and weasel-icons/shopping-cart, plus typed state lists. Play and Pause use control states (idle, hover, pressed); the application owns playback. Clock, Timer and Truck retain phase when activity stops. Quiet states remain still even with alive; finite capture, selection and insertion actions play once per entry.

Upgrading from 0.1.0

Version 0.2.0 also includes SparklesIcon and the single-contour SparkleIcon (both idle, shimmering, blink, dimmed), StarIcon (idle, shooting, starred, loading) and WaveIcon (idle, flowing, energetic, flat), with direct exports at /sparkles, /sparkle, /star and /wave. Sparkles uses blink and Star uses shooting. RefreshIcon, CopyIcon and LinkIcon have four states; EyeIcon, CheckIcon and CloseIcon intentionally have three.

0.2.0 adds Shield, Cursor, Clapperboard, Plug, Bulb, Alert, Badge Check, Replace, Delete and Swap, with the latest state feedback fixes. Leaf and its weasel-icons/leaf export have been removed; remove or replace any Leaf imports before upgrading. Existing retained icon imports continue to work. The new motions have geometry and lifecycle regression coverage, but are not newly browser-profiled performance guarantees.

Common optional props: state, size, color, accentColor, strokeWidth, speed, alive, className.

• alive={false} (default) transitions to the state, then settles.
• strokeWidth defaults to 1.65 SVG units; pass a different width to override it.
• alive adds varied continuous in-state behavior. System reduced-motion preferences take precedence.
• color and accentColor default to currentColor.
• Dog, monkey, heart, ship and alert accept small icon-specific colors objects, with exported types such as DogColors. Alert's critical punctuation defaults to red; use colors={{ critical: 'your-colour' }} to override it without recolouring the triangle.
• Neutral interiors use --weasel-surface (white by default), including Dog, Ship, Lock, Mail, Folder, Wallet, Package, Sliders and the cart item. Set it on their parent for other backgrounds. Monkey supports colors.face.

SVGs are decorative and hidden from screen readers. Label the containing control or adjacent status text. Do not communicate state using only color or animation.

This package installs into node_modules; it does not copy source into your components directory and does not expose an npx command. Upgrading the dependency brings new icons and fixes; it does not update already deployed websites until you rebuild and deploy them.

License

Original code is MIT licensed. Adapted source geometry retains its upstream notices in THIRD_PARTY_NOTICES.md, included with this package. The website, mascot, fonts, tests, and authoring tools are not part of this package.