@editora/icons

@editora/icons

[!IMPORTANT] Live Website: https://editora-ecosystem.netlify.app/
Storybook: https://editora-ecosystem-storybook.netlify.app/?path=/story/ui-icons-catalog--all-icons

Framework-agnostic SVG icon library for the Editora UI ecosystem, with 500+ ready-to-use icons.

Use this package when you need:

• 500+ generic UI, product, utility, and logo icons,
• raw icon definitions and registry APIs,
• SVG string rendering in any framework/runtime,
• icon aliases and runtime extension,
• bridge support to register icons into @editora/ui-core.

Installation

npm install @editora/icons

Quick Start

import { renderIconSvg, listIcons } from '@editora/icons';

const svg = renderIconSvg('check', {
  variant: 'outline',
  size: 16,
  color: 'currentColor',
  strokeWidth: 1.5,
  decorative: true
});

console.log(svg);
console.log(listIcons().slice(0, 10));

Package Exports

Definitions + registry

• iconDefinitions
• iconNameList
• getIcon(name)
• hasIcon(name)
• listIcons()
• listIconAliases()
• registerIcon(definition)
• registerIcons(definitions)
• resolveIcon(name, variant?)

Rendering

• renderIconSvg(name, options?)
• iconToDataUri(name, options?)

Integration helper

• registerWithEditoraUI(registerFn)

Types

• IconDefinition
• IconGlyph
• IconNode
• IconRenderOptions
• IconVariant
• ResolvedIcon
• IconTag
• IconAttrValue

Core Concepts

1) Names and normalization

Icon names are normalized internally:

• lowercase
• spaces/underscores converted to -

So "Chart Line", "chart_line", and "chart-line" resolve to the same key pattern.

2) Variants

Supported variants:

• outline (default fallback)
• solid
• duotone

If a requested variant is missing, the renderer automatically falls back to outline.

3) Aliases

Definitions can include aliases. getIcon and resolveIcon check aliases automatically.

API Usage

Registry lookup

import { hasIcon, getIcon, resolveIcon, listIconAliases } from '@editora/icons';

if (hasIcon('navigation')) {
  const def = getIcon('navigation');
  const resolved = resolveIcon('navigation', 'duotone');
  console.log(def?.name, resolved?.variant);
}

console.log(listIconAliases());

Render SVG string

import { renderIconSvg } from '@editora/icons';

const svg = renderIconSvg('chart-line', {
  variant: 'duotone',
  size: 20,
  color: 'var(--ui-fg)',
  secondaryColor: 'var(--ui-fg-muted)',
  strokeWidth: 1.5,
  strokeLinecap: 'round',
  strokeLinejoin: 'round',
  title: 'Revenue trend'
});

Render as Data URI

import { iconToDataUri } from '@editora/icons';

const uri = iconToDataUri('check-circle', {
  size: 14,
  color: '#16a34a',
  decorative: true
});

// Example: CSS background-image
// background-image: url("${uri}");

IconRenderOptions

Common options for renderIconSvg and iconToDataUri:

Option	Type	Default	Notes
variant	'outline' | 'solid' | 'duotone'	'outline'	Falls back to outline when unavailable.
size	number | string	15	Sets SVG width/height.
color	string	'currentColor'	Primary color.
secondaryColor	string	color	For duotone secondary paths.
strokeWidth	number	1.5	Stroke thickness.
absoluteStrokeWidth	boolean	false	Keeps perceived stroke width stable across sizes.
strokeLinecap	'butt' | 'round' | 'square'	'round'	Applied when stroke exists.
strokeLinejoin	'miter' | 'round' | 'bevel'	'round'	Applied when stroke exists.
title	string	undefined	Adds <title>.
ariaLabel	string	inferred	Accessibility label for semantic icons.
decorative	boolean	inferred	If true, outputs aria-hidden/presentation role.
rotate	number	0	Rotation in degrees.
flip	'horizontal' | 'vertical' | 'both'	undefined	Flip transform.
rtl	boolean	false	Mirrors icons marked rtlMirror.
className	string	undefined	Applied on root <svg>.
style	string	undefined	Inline style text on root <svg>.
attrs	Record<string, ...>	undefined	Extra root attributes (data-*, etc.).

Register Custom Icons

You can extend the registry at runtime.

import { registerIcon, renderIconSvg, type IconDefinition } from '@editora/icons';

const CustomBillingIcon: IconDefinition = {
  name: 'billing-custom',
  aliases: ['billing-custom-outline'],
  tags: ['finance', 'invoice'],
  categories: ['business'],
  viewBox: '0 0 15 15',
  variants: {
    outline: {
      nodes: [
        { tag: 'rect', attrs: { x: 2, y: 1.5, width: 11, height: 12, rx: 2, fill: 'none', stroke: 'currentColor' } },
        { tag: 'line', attrs: { x1: 4, y1: 5, x2: 11, y2: 5, stroke: 'currentColor' } },
        { tag: 'line', attrs: { x1: 4, y1: 8, x2: 9.5, y2: 8, stroke: 'currentColor' } }
      ]
    }
  }
};

registerIcon(CustomBillingIcon);

console.log(renderIconSvg('billing-custom'));

Register many icons:

import { registerIcons } from '@editora/icons';

registerIcons([/* IconDefinition[] */]);

Integrations

With @editora/react-icons

@editora/react-icons consumes this package for React components and typed name APIs.

With @editora/ui-core

Use the built-in bridge to register all available icons into a UI core icon registry.

import { registerWithEditoraUI } from '@editora/icons';

// registerFn(name, svg) should add icon markup into your UI icon store.
registerWithEditoraUI((name, svg) => {
  console.log('registered', name, svg.length);
});

Accessibility Notes

• Decorative icons should use decorative: true (or omit title/ariaLabel so it is inferred).
• Semantic icons should provide title or ariaLabel.

Performance Notes

• @editora/icons is sideEffects: false for tree-shaking.
• Prefer reusing resolved icon names in app code instead of repeated normalization in hot loops.
• For large CSS/icon sprites, iconToDataUri can be cached by (name, variant, size, color) keys.

Development

cd packages/icons
npm run build

Troubleshooting

• Empty SVG returned:
  • Icon name is missing or misspelled.
  • Requested variant is unavailable and definition has no usable outline.
• Alias not resolving:
  • Verify alias is registered in the icon definition.
• Unexpected stroke/fill:
  • Check custom node attrs and variant nodes for fill/stroke overrides.