# pixelarticons: a pixel icon set with a hard 24 by 24 rule
> pixelarticons is an icon set drawn on a strict 24 by 24 grid with no anti-aliasing, pure path elements and fill set to currentColor, shipped as raw SVG files, React components, a CDN route and a prebuilt webfont. The free set holds 1036 icons, the paid set 5497, and the upgrade command writes into the installed package rather than replacing it.
**halfmage/pixelarticons** — 👾 Beautiful pixel icons. For the pixel vibes.
- Repository: https://github.com/halfmage/pixelarticons
- Website: https://pixelarticons.com
- Stars: 877 · Forks: 32
- Language: JavaScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/halfmage-pixelarticons
## The three rules that define the set
The set is described as 1036 free pixel art icons drawn on a strict 24 by 24 grid, with no anti-aliasing, pure path elements and fill set to currentColor. Those three constraints are the design, and they are enforced rather than recommended. The contribution rules in the README restate them: viewBox of 0 0 24 24, path elements only, fill of currentColor, paths that align to the pixel grid with no sub-pixel coordinates, and filenames in kebab-case that describe function rather than appearance. The last rule is the one that pays off later, because an icon named for what it does rather than what it looks like survives a redraw. The repository has a validate script that checks every SVG against the design rules, so a contribution that breaks the grid is caught by tooling rather than by a reviewer's eye.
## Four delivery routes from the same package
The same icon can arrive four ways, and the choice is mostly about how much you want the bundler to do. As raw SVG files, the svg directory contains every icon standalone and you drop them into a project directly. As React components, each icon ships with full TypeScript types and accepts all standard SVG props including width, height, className, style and onClick, with a default size of 24 by 24 and a recommendation to use multiples of 24 for the sharpest rendering: 24px, 48px, 72px, 96px. Via a CDN, unpkg serves any icon by name with no install at all. And as a webfont, the package ships prebuilt woff2, woff, ttf, eot and svg files with stylesheets in CSS, Less, SCSS and Stylus, so nothing has to be generated.
## React imports and the tree-shaking detail
The React usage is the one most projects will take, and it has two levels.
```jsx
import { Heart, Home, Bell, Mail, Lock } from 'pixelarticons/react'
export default function App() {
return (
)
}
```
The first level imports from the package root, and the second imports a single icon by path so a bundler can drop the rest.
```jsx
import { Heart } from 'pixelarticons/react/Heart'
```
Naming is mechanical on both sides. Icon names are PascalCase matching the SVG filename, so alarm-clock.svg becomes AlarmClock, and style variants keep their suffix, so heart-solid.svg becomes HeartSolid while the base style has none. The package manifest exports map has an explicit entry for react and a wildcard for react/*, which is what makes the per-icon import path resolve, and React is a peer dependency at version 16 or newer rather than a bundled one.
## The webfont covers the free set and nothing else
The webfont route is the simplest to use and the one with a catch that is easy to miss. The package ships a prebuilt webfont with one class per icon, named pixelart-icons-font- followed by the icon name.
```html
```
The catch is that the webfont covers the free icons. The upgrade command adds SVG files and React components and does not rebuild the font, so the paid icons need the React or raw SVG route. The font is built from the SVG sources with svgtofont, which the package manifest exposes as a script along with the React component generator and the validation and browser preview scripts. Since the font is prebuilt, the generation step is not something you run, which is convenient until you need an icon that is not in the free set and the font route cannot give it to you.
## How the paid icons get into your project
The free package includes 1036 icons. If you have bought a licence, the upgrade command unlocks the full set.
```bash
npx pixelarticons upgrade --key=YOUR_LICENSE_KEY
```
It verifies the licence, downloads every icon into the installed package and regenerates the React components, and your imports do not change, since pixelarticons/react and pixelarticons/svg simply resolve more icons. The licence key comes from your Gumroad library or from the purchase confirmation email, and the command needs the unzip program and network access, and accepts keys for the Base Pro product. Because it writes into the installed package, a clean install brings back the free set, so the documented workaround is a postinstall script with the key in an environment variable or a CI secret.
```json
{
"scripts": {
"postinstall": "pixelarticons upgrade --key=$PIXELARTICONS_LICENSE_KEY"
}
}
```
For offline builds the guide says to copy node_modules/pixelarticons/svg/*.svg into your own repository once and treat the icons as project assets.
## How the set grew, and what the paid tier actually buys
The what's new section is a good record of how an icon set becomes a business. In July 2026 the complete set reached 4421 icons and the full alphabet shipped in three styles, plain letters, circle-framed and square-framed, alongside new people, animals, energy, media, currency and loader icons, with 64 of the 108 new icons landing in the free set and bringing it to 880. In August 2026 the free set grew to 1036 as 159 icons moved from Pro to free, covering the brand icons developers ask for most, among them GitHub, X, Discord, Figma, Docker and Linux, plus missing interface essentials like pause, stop, refresh, sun, sliders, dollar and percent, in their sharp, glyph and solid variants, with every icon staying MIT licensed. In October 2026 the full set reached 5497 icons with a website redesign, a clearer pricing page and a brand page, while the free set stayed at 1036. So the paid tier is not the newer icons, it is the volume.
## The repository layout and the tooling
The top-level listing is small for a project of this size. There is an index.js and an index.d.ts at the root, the svg directory with the icon files, a bin directory holding the upgrade entry point that the manifest registers as the pixelarticons command, and a scripts directory with the generators. The build tooling is minimal: svgtofont for the font and np for releases, plus a.svgtofontrc configuration file for the font generator and an.npmignore for what stays out of the package. The type declarations are shipped from the root rather than generated into a types folder. The scripts also include a browser command that generates a preview page of every icon and opens it, which is the fastest way to see what is actually in the set.
## Where pixelarticons is the wrong choice
Four limits apply. It is deliberately pixel art, so it will sit badly next to a smooth, rounded or thin-stroke icon set, and mixing the two is worse than either alone. The free and paid sets are different sizes, 1036 against 5497, which means a design that uses an icon only present in the paid tier breaks for anyone on the free package, and the documentation does not enumerate which icons are free in a way you can check offline. The upgrade mechanism writes into node_modules, which is at odds with reproducible installs, with lockfile integrity checks and with any pipeline that hashes its dependency tree, so teams that care about that have to vendor the SVG files instead. And there is no test suite: the manifest's test script is a placeholder that reports no test specified, so the validate script is the only automated check, and it checks geometry rather than whether an icon looks right.
## Conclusion
Use pixelarticons when you want an icon set with a visible pixel aesthetic rather than smooth vector shapes, because the grid discipline is what produces the look and a mixed set would defeat the point. Do not assume the free and paid sets are the same thing, since the free set holds 1036 of 5497 and the paid icons arrive through an upgrade command that writes into node_modules. Verify first that the grid rules match your design, since paths must align to the pixel grid with no sub-pixel coordinates and filenames describe function rather than appearance, that your build can absorb a postinstall step if you want the paid icons to survive a clean install, and that the webfont covers only the free icons, since the upgrade command does not rebuild it.
## FAQ
### How many icons are in the pixelarticons set?
The free package includes 1036 icons, and the full set holds 5497 as of October 2026. The free set grew from 880 in July 2026 to 1036 in August 2026, when 159 icons moved from Pro to free.
### How do I install pixelarticons?
Run npm install pixelarticons. You can then import the React components, drop the raw SVG files from the svg directory into your project, load an icon straight from unpkg, or import the prebuilt webfont stylesheet.
### What are the design rules for pixelarticons?
A viewBox of 0 0 24 24, path elements only, fill of currentColor, paths aligned to the pixel grid with no sub-pixel coordinates, and kebab-case filenames describing function rather than appearance. The repository ships an npm run validate script that checks every SVG against these rules.
### How do I unlock the paid icons?
Run npx pixelarticons upgrade --key=YOUR_LICENSE_KEY, which verifies the licence, downloads every icon into the installed package and regenerates the React components. Your imports do not change, and the key comes from your Gumroad library or the purchase confirmation email.
### Does the pixelarticons webfont include the paid icons?
No. The webfont covers the free icons only, because the upgrade command adds SVG files and React components and does not rebuild the font. Paid icons need the React or raw SVG route.
## Sources
- [halfmage/pixelarticons on GitHub](https://github.com/halfmage/pixelarticons)
- [License: MIT](https://github.com/halfmage/pixelarticons/blob/master/LICENSE)
- [Project website](https://pixelarticons.com)
- [README](https://github.com/halfmage/pixelarticons/blob/master/README.md)
- [Releases](https://github.com/halfmage/pixelarticons/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/halfmage-pixelarticons