EagleICON

EagleICON is a minimalist SVG icon engine for developers who want speed, accessibility, and zero dependencies.

It renders icons through an SVG sprite and <use> references, so the DOM stays light as your icon set grows.

Features

• Performance first: Zero dependencies. Under 2KB gzipped runtime.
• CSS-driven: Control stroke-width, fill, color, rotate, and flip via CSS variables and data-* attributes.
• Typed icons: Exported EagleIconId union with autocomplete for every shipped icon.
• Accessible: Automatic aria-hidden for decorative icons and <title> support when labeled.
• SSR-ready: svgMarkup() returns HTML without needing a browser Document.
• Optional React adapter: @demirkartal/eagleicon/react.

Installation

npm install @demirkartal/eagleicon

Copy the sprite from the package (or serve your own subset):

cp node_modules/@demirkartal/eagleicon/dist/svg/eagleicon.svg public/eagleicon.svg

Or import the published path:

import "@demirkartal/eagleicon/css";
// sprite URL: resolve from "@demirkartal/eagleicon/svg" in your bundler/static host

Implementation

1. Stylesheet

@import "@demirkartal/eagleicon/css";

Legacy path still works: @demirkartal/eagleicon/dist/css/eagleicon.css.

2. JavaScript / TypeScript

import EagleIcon, { type EagleIconId } from "@demirkartal/eagleicon";

const eagle = new EagleIcon(document, "/assets/eagleicon.svg");

document.body.append(eagle.svgElement("search"));

const icon = eagle.svgElement(
  "arrow-up",
  ["btn-icon"],
  { "stroke-width": "2.5", fill: "currentColor", "data-rotate": "90" },
  "Scroll to top",
);

// SSR / string output (no Document needed for the markup itself)
const html = eagle.svgMarkup("home", [], {}, "Home");

svgElement / svgMarkup accept EagleIconId. Invalid ids are still allowed as plain strings at runtime if you extend the sprite yourself.

3. React (optional)

import { EagleIconReact } from "@demirkartal/eagleicon/react";

export function SearchButton() {
  return (
    <EagleIconReact
      id="search"
      spriteUrl="/assets/eagleicon.svg"
      title="Search"
      iconClassName="btn-icon"
    />
  );
}

react is an optional peer dependency.

Design control

.eagleicon {
  --svg-stroke-width: 1.75;
  --svg-fill: none;
  color: #4a5568;
  width: 16px;
  height: 16px;
}

.eagleicon[data-rotate="90"] { /* built-in */ }
.eagleicon[data-flip="horizontal"] { /* built-in */ }

Supported rotate values: 45, 90, 135, 180, 225, 270, 315. Flip: horizontal, vertical.

Sprite hosting notes

External <use href="/sprite.svg#id"> requires the sprite to be same-origin or served with CORS headers that allow embedding. For strict CSP / cross-origin setups, host the sprite on the same origin as the page, or inline the sprite into the document.

Constructor options:

• spriteUrl (required): path or URL to the sprite
• prefix (default "eagleicon"): CSS class applied to every icon

Available icons

Curated set of 179 UI icons:

• Arrows: arrow-up, arrow-down, arrow-left, arrow-right, chevron-up, chevron-down, chevron-left, chevron-right
• UI / actions: search, menu, close, plus, minus, globe, sort, sort-up, sort-down, home, user, users, user-plus, user-minus, user-check, check, trash, edit, external-link, copy, cut, paste, clipboard, save, link, share, download, upload, refresh, undo, redo, login, logout, bookmark, pin, paperclip, power, zap, moon, sun, translate, palette, key, shield
• Editor: bold, italic, underline, align-left, align-center, align-right, align-top, align-middle, align-bottom, newspaper, rss, quote, book-open, pen-line
• Commerce: cart, cart-add, bag, heart, tag, percent, credit-card, truck, package, receipt, wallet, dollar-sign, store, gift, ticket, barcode, qr-code, banknote, coins, bank, refund, subscription
• Panel: dashboard, settings, filter, eye, eye-off, lock, unlock, bell, calendar, chart, more-horizontal, more-vertical, file, file-plus, folder, folder-open, folder-plus, archive, printer, list, layout-grid, table, columns, rows, sidebar, panel-left, panel-right, maximize, minimize, expand, shrink, drag, layers, code, extension, sliders, wrench, database, server, cloud, terminal, activity
• Builder: move, hand, mouse-pointer, crosshair, box-select, group, ungroup, bring-front, send-back, section, component, spacer, divider, crop
• Status / media: info, warning, check-circle, x-circle, alert-circle, help-circle, ban, flag, clock, history, loader, image, camera, video, play, pause, stop, mail, map-pin
• Communication: phone, whatsapp, message, inbox, send, at-sign, mail-open, mail-plus, reply, forward, newsletter, spam, megaphone
• Shapes & ratings: circle, square, star

Filled look: set fill="currentColor" on the host (no separate -fill icons).

Runtime list: import { EAGLE_ICON_IDS } from "@demirkartal/eagleicon".

Subset sprites

Build a smaller sprite for production pages:

node generate-sprite.js --src src/svg --output dist/svg/app.svg --ids home,search,user,menu

Add --minified for a single-line sprite.

Why EagleICON?

| Feature | Traditional SVGs | Icon Fonts | EagleICON | | :---------------- | :--------------: | :--------: | :---------------------: | | HTTP Requests | High | Low | Low (1 Sprite) | | DOM Weight | Heavy | Light | Light (Reference) | | Styling | Limited | Easy | Infinite (CSS Vars) | | Type Safety | No | No | Yes | | Accessibility | Manual | Poor | Automatic |

License

Distributed under the MIT License. See LICENSE for more information.