@ecync/social-icons

Lightweight, tree-shakeable React components for social network brand icons — plain mono glyphs, official brand-color glyphs, and colored "badge" versions — built for low bundle/runtime cost and typed end to end.

Install

npm install @ecync/social-icons

react >=17 is a peer dependency; nothing else is required at runtime.

Usage

import { Telegram, TelegramBadge } from '@ecync/social-icons';

function Footer() {
  return (
    <a href="https://t.me/yourchannel" aria-label="Telegram">
      <Telegram size={20} />
    </a>
  );
}

function BadgeList() {
  return <TelegramBadge size={40} shape="circle" />;
}

Every icon accepts the same props (IconProps):

| Prop | Type | Default | Notes | | --------- | ------------------- | ---------------- | --------------------------------------------------------------- | | size | number \| string | 24 | Sets both width and height. | | color | string | 'currentColor' | Glyph color for variant="mono". Ignored by variant="color". | | variant | 'mono' \| 'color' | 'mono' | mono follows color; color uses the brand's official hex. | | title | string | — | Accessible name. Omit for a decorative, aria-hidden icon. |

Plus every standard SVG prop (className, style, onClick, data-*, …) and a forwarded ref to the underlying <svg> element.

<Reddit variant="color" size={32} />
<X color="#1a1a1a" />
<Google ref={svgRef} className="social-icon" />

Badges

Each icon also ships a <NameBadge> component: a white glyph over a rounded shape filled with the brand's official color — matching the colored badge style from the source design.

import { SpotifyBadge } from '@ecync/social-icons';

<SpotifyBadge size={48} shape="square" title="Spotify" />;

BadgeProps adds one option on top of the base props: shape?: 'circle' | 'square' (default 'circle').

Choosing an icon by name at runtime

For cases like a CMS-driven list of social links, use the dynamic Icon/Badge components:

import { Icon, type IconName } from '@ecync/social-icons';

function SocialLink({ network }: { network: IconName }) {
  return <Icon name={network} size={20} />;
}

Icon and Badge import every icon in the package, so prefer the named component (import { Telegram } from '@ecync/social-icons') whenever the icon is known at build time — it's the only way a bundler can tree-shake the rest away.

Guaranteed tree-shaking via subpath imports

The barrel export above tree-shakes correctly in any bundler that respects "sideEffects": false (Webpack, Rollup, esbuild, Vite, etc.). If you need it independent of bundler configuration, import the icon's own module directly:

import { Telegram } from '@ecync/social-icons/icons/telegram';

Available icons

Behance, Dribbble, Google, LinkedIn, OpenAI, QQ, Reddit, Snapchat, Spotify, Telegram, Threads, Trello, Tumblr, Twitch, Vine, WeChat, Weibo, X.

Each name above is exported both as a plain icon (Behance) and a badge (BehanceBadge). See docs/ICONS.md for the full table with each brand's official hex color.

Documentation

• docs/API.md — full prop/type reference for every export.
• docs/ICONS.md — icon gallery, brand colors, and how to add a new brand.
• docs/ARCHITECTURE.md — how the package is structured and why.
• CONTRIBUTING.md — local dev workflow and PR conventions.
• CHANGELOG.md — release history.

Design notes

• One render path. Every icon is a thin { viewBox, path, brandColor } definition passed through a single shared createIcon factory (see src/core) — render logic is compiled once, not duplicated per icon, so the library's JS cost grows with path-data bytes only.
• No runtime dependencies, no icon font, no CSS-in-JS. Just memoized, ref-forwarding SVG components.
• Accessible by default. Icons are aria-hidden (decorative) unless you pass title, in which case they render as a labeled role="img" element with an inline <title>.
• Accurate brand marks. Path data is sourced from Simple Icons (CC0 1.0), not hand-traced, to avoid inaccuracies. Brand marks remain the property of their respective owners; inclusion here does not imply endorsement.

Development

npm install
npm run typecheck   # tsc --noEmit
npm run lint         # eslint
npm run test         # vitest
npm run build        # tsup -> dist/ (esm + cjs + d.ts)

Icon source modules under src/icons/* are generated by scripts/generate-icons.mjs from raw single-path brand SVGs; see that script for how to regenerate or add a brand.

Releases are managed with Changesets: run npm run changeset to describe a change, then merge — CI opens a version-bump PR and publishes to npm once that PR lands.

License

MIT © ecync. Icon path data: CC0 1.0 (Simple Icons). See LICENSE.