Docs

Install

The package holds the SVG source files, ready-made React components with TypeScript types, and a webfont. Node 18 or later.

npm install pixelarticons
# pnpm add pixelarticons
# yarn add pixelarticons
# bun add pixelarticons

Without an install

Every free icon is on unpkg. Replace heart with any icon name in kebab-case.

<img src="https://unpkg.com/pixelarticons@latest/svg/heart.svg" width="24" height="24" alt="Heart" />

Unlock the Pro icons through npm

A Pro license does not move you to a different package. It unlocks the package you already installed. Run the upgrade command in your project:

npx pixelarticons upgrade --key=YOUR_LICENSE_KEY

Your import paths do not change. The icons that were missing before now resolve:

import { Heart, Sliders, AlarmClockCheck } from 'pixelarticons/react'

// Heart shipped in the free set. Sliders and AlarmClockCheck were Pro only,
// and resolve from the same import after the upgrade.
<Sliders width={48} height={48} />

Fresh installs, teammates and CI

The upgrade writes into the installed package. A clean install therefore brings back the free set, on your machine and on the build server. Pick one of these two patterns.

Option A: run it after every install

Add a postinstall script and keep the key in an environment variable, so it never reaches your repository. Set the same variable as a secret in your CI.

{
  "scripts": {
    "postinstall": "pixelarticons upgrade --key=$PIXELARTICONS_LICENSE_KEY"
  }
}

On Windows PowerShell the variable syntax is $env:PIXELARTICONS_LICENSE_KEY. Builds that run without network access must use option B.

Option B: copy the icons into your repository

The most predictable option, and the one to pick for offline builds. Run the upgrade once, copy the SVG files across, and treat them as project assets.

# Run once, then commit the result to your own repository.
npx pixelarticons upgrade --key=YOUR_LICENSE_KEY
mkdir -p src/icons
cp node_modules/pixelarticons/svg/*.svg src/icons/

Keep that repository private. The Pro license covers use in your products, not redistribution of the icon set.

React

Every icon is a component with full TypeScript types. Components accept all standard SVG props, default to 24 by 24, and paint with currentColor, so text colour utilities work on them.

import { Heart, Home, Bell } from 'pixelarticons/react'

export default function App() {
  return (
    <>
      <Heart width={48} height={48} />
      <Home className="text-blue-500" />
      <Bell style={{ color: 'red' }} onClick={ring} />
    </>
  )
}

Bundlers that do not tree-shake barrel files can import a single component instead:

import { Heart } from 'pixelarticons/react/Heart'

Import from pixelarticons/react or pixelarticons/svg, never from the package root. The components are client side, so render them with client:only="react" in Astro.

Raw SVG and other frameworks

There is no Vue or Svelte package, and none is needed. The svg/ directory holds one file per icon, so any framework can consume it.

<!-- Straight from node_modules, bundled by Vite, webpack or Rollup -->
<img src="/node_modules/pixelarticons/svg/heart.svg" width="24" height="24" alt="Heart" />

To colour an icon with CSS, inline it instead of loading it through an img tag:

// Vite, Astro, Nuxt and SvelteKit: import the file as a string
import heart from 'pixelarticons/svg/heart.svg?raw'

// Vue
<span v-html="heart" />

// Svelte
{@html heart}

// Astro
<Fragment set:html={heart} />

For an auto-imported icon component in Vue, Svelte or Solid, register the directory as a custom collection:

// vite.config.js
import Icons from 'unplugin-icons/vite'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default {
  plugins: [
    Icons({
      customCollections: {
        px: FileSystemIconLoader('node_modules/pixelarticons/svg'),
      },
    }),
  ],
}

// Then, in any component:
import IconHeart from '~icons/px/heart'

Icon font

The package ships a prebuilt webfont in woff2, woff, ttf, eot and svg, with a stylesheet in CSS, SCSS, Less and Stylus. One class per icon.

import 'pixelarticons/fonts/pixelart-icons-font.css'

<i class="pixelart-icons-font-heart"></i>
<i class="pixelart-icons-font-heart-solid"></i>

The webfont covers the free icons. The upgrade command adds SVG files and React components, and does not rebuild the font, so Pro icons need one of the routes above.

CSS and Tailwind

A CSS mask keeps the icon colourable while it stays an external file. The element colour drives the icon colour, so hover and dark mode need no second file.

.icon-heart {
  width: 24px;
  height: 24px;
  background-color: currentColor;
  mask: url('/icons/heart.svg') center / contain no-repeat;
}

With inline SVG, Tailwind utilities are enough:

<!-- Recolor and resize an inline SVG with utilities alone -->
<span class="text-primary [&_svg]:w-12 [&_svg]:h-12">
  <!-- inline <svg fill="currentColor"> here -->
</span>

Names and styles

File names are kebab-case and describe function, not appearance. React components use the PascalCase form of the same name. Most icons exist in four styles; the base style carries no suffix.

heart.svg          ->  <Heart />          base, the default
heart-sharp.svg    ->  <HeartSharp />     hard 90 degree corners
heart-solid.svg    ->  <HeartSolid />     filled, rounded corners
heart-glyph.svg    ->  <HeartGlyph />     filled, hard corners
alarm-clock.svg    ->  <AlarmClock />     kebab-case turns into PascalCase

Compare the four styles to see which one fits your interface, or search the full set to find an exact name.

Sizing rules

Each icon sits on a 24 by 24 grid with no anti-aliasing. Scale in multiples of 24 and the pixels stay square. Scale to 30 or 40 pixels and the edges blur, because the grid no longer lands on whole device pixels.

<!-- Good: multiples of the 24px grid -->
<Heart width={24} height={24} />
<Heart width={48} height={48} />
<Heart width={96} height={96} />

<!-- For raster scaling, keep the edges hard -->
<img src="heart.svg" width="96" height="96" style="image-rendering: pixelated" />

Mini icons use an 8 by 8 grid, so their multiples are 8, 16, 32 and 64.

Mini, Prime and design files

The npm package carries the Base set. Mini and Prime are separate sets with their own licenses, delivered as downloads from Gumroad rather than through npm. Drop their SVG files into your project and use them exactly like the samples above.

Designers can also start from the free Figma community file. Every license includes the full Figma library.

Troubleshooting