Naive Icons

English | 中文

Hand-drawn "naive folk art" style SVG icon library, built for React and TypeScript

🤖 AI Agent Skill — install it into Claude Code, Cursor, Codex and friends,
and they can pick icons by meaning, emit ready-to-paste code, and know the design rules.
npx skills add guokaigdg/naive-icons  ·  See details →

Each icon is drawn on a 48x48 grid with a 3.5 stroke, rounded line caps, and a retro palette — keeping the charming clumsiness and warmth of hand-drawn illustration. Some icons even feature a pair of dot eyes and a little smile, adding a touch of humanity to your interface.

Features

• Icons spanning 11 categories: interface, actions, media, navigation, animals, food, and more
• Every icon ships as both an SVG source file and a React TSX component
• Full TypeScript types: IconProps, IconName, IconComponent, PaletteColor, NAIVE_PALETTE
• Exports scaledStroke / resolveStrokeWidth / normalizeIconProps for building your own icons
• Supports currentColor to follow the surrounding text color
• Official Agent Skill: one command installs it into your AI coding agent, which can then pick icons by meaning and emit ready-to-paste code

AI Agent Skill

Install it into your AI coding agent (Claude Code, Cursor, Codex, …) and it can pick icons by meaning, emit ready-to-paste code, and know this library's design rules.

npx skills add guokaigdg/naive-icons

You do not need to install the package first. Start a new session afterwards, then just ask:

• "Give this login page a set of naive icons"
• "Find an icon that means 'already read'"

The skill bundles the full icon catalog, the design spec, usage patterns and every SVG source file, so the agent can generate code even when the package isn't installed in your project. Re-run the same command after upgrading the library to update it.

Installing the skill and using the components are separate things. You only need npm install naive-icons from the Installation section below when you actually want to import { HomeIcon } from 'naive-icons' in your own code.

Installation

npm install naive-icons

yarn add naive-icons

pnpm add naive-icons

Naive Icons only depends on React and supports React 16.8 and above (including React 18 and 19).

Quick Start

import { HomeIcon, HeartIcon, PenguinIcon } from 'naive-icons';

export function Example() {
  return (
    <nav>
      <HomeIcon size={24} />
      <HeartIcon size={24} color="#E76F51" />
      <PenguinIcon size={48} strokeWidth={7} />  {/* doubles every stroke */}
    </nav>
  );
}

Tree-shaking works out of the box: the package is ESM and sets sideEffects: false, so a named import pulls in only the icons you actually use:

import { HomeIcon, SearchIcon } from 'naive-icons';

Or import a single icon straight from a subpath, bypassing the entry entirely:

import { HomeIcon } from 'naive-icons/icons/HomeIcon';

Both forms produce the same bundle size (~0.9 KB minified for a single icon). The repo has a tests/bundle-size.test.ts guarding that number, so a build change that breaks tree-shaking fails the test suite.

To follow the parent text color, pass currentColor explicitly — the default is ink #2A2A2A and is not inherited automatically:

<span style={{ color: '#264653' }}>
  <HomeIcon size={20} color="currentColor" />
  Home
</span>

Add an accessibility title:

<HomeIcon size={24} title="Back to home" />

Component Props

Every Naive Icon component extends the native SVGProps<SVGSVGElement>, so you can pass any SVG attribute directly, such as className, onClick, or style.

The fill row deserves a note: the naive look depends on solid colour blocks, so 489 of the 730 primitives hard-code their own fill and a root fill has no effect on them. That is the style itself, not a bug — to recolour, switch the stroke with color, or pick from the ten colours in NAIVE_PALETTE. | width / height | number | string | follows size | Set width or height individually; takes precedence over size, and the side you omit falls back to size |

import type { IconProps } from 'naive-icons';

interface IconProps extends SVGProps<SVGSVGElement> {
  size?: number | string | null;
  color?: string;
  strokeWidth?: number | string;
  fill?: string;
  title?: string;
}

// also exports scaledStroke / resolveStrokeWidth / normalizeIconProps

Using the SVG Directly

If your project isn't React, you can use the source files in the svg/ directory. Every SVG is self-contained with no external references.

<img src="https://stargazers.cn/raw/guokaigdg/naive-icons/main/naive-icons/svg/home.svg" width="24" height="24" alt="Home" />

To follow the surrounding text color when inlining, replace stroke="#2A2A2A" with stroke="currentColor":

<svg viewBox="0 0 48 48" width="24" height="24" fill="none"
     stroke="currentColor" stroke-width="3.5"
     stroke-linecap="round" stroke-linejoin="round">
  <!-- Copy the path content from svg/home.svg -->
</svg>

You can also build an SVG sprite or icon font — the source files are simple enough to work with.

Palette

import { NAIVE_PALETTE } from 'naive-icons';

Design Principles

Naive Icons follows four fixed rules. They should be respected when adding new icons.

1. Grid & bleed: All graphics are drawn on a 48x48 canvas, keeping at least 3 units between the main body and the canvas edge.
2. Stroke: A unified 3.5 width with round caps and joins, and no dashed lines.
3. Color: The 9 palette colors set the default tone; other solid colors are allowed when genuinely needed (e.g. brand colors) — no gradients, shadows, or semi-transparent overlays.
4. Personality: Slight asymmetry is welcome; encourage dot eyes and a smile on living subjects to keep the hand-drawn clumsiness.

Local Development

git clone https://github.com/guokaigdg/naive-icons.git
cd naive-icons
npm install

Common scripts:

npm run build        # Build dist with tsup (ESM + CJS + type declarations)
npm run dev          # Watch mode build
npm run typecheck    # Type check
npm run website      # Preview the site locally (Python static server, port 8080)
npm run icons:build  # Regenerate SVG and TSX from script definitions
npm run icons:add    # Incrementally add icons without overwriting existing files

prepublishOnly runs the build automatically on publish, so there is no need to run npm run build manually.

The build output is dist/index.mjs (ESM), dist/index.js (CJS), and dist/index.d.ts / dist/index.d.mts (type declarations). The exports field in package.json points to the correct file for each import / require condition. React is declared as external and is not bundled.

The website is a fully static site (no build step, no dependencies). You can open website/index.html directly: browse all icons, filter by category, search, adjust size and stroke color live, switch between light/dark/grid preview backgrounds, and click any icon to view React usage, copy code, or download the SVG. It supports light/dark themes (follows the system, with manual toggle remembered) and lets you navigate between icons with arrow keys in the modal.

Browser Support

Naive Icons outputs standard SVG 1.1 and supports all modern browsers (the last two major versions of Chrome, Firefox, Safari, and Edge). The React components contain no browser-specific APIs and can be safely used in server-side rendering environments.

License

MIT License. See LICENSE.

All icons are original works, free to use in personal and commercial projects without attribution.

Sponsor

If this project has been helpful, consider treating the developer's cat to a can of food — after all, there's a cat supervising the code behind every icon. Feed the cat a can